Skip to content

Troubleshooting

An import fails

Why a media file is refused or fails to import, and what to change.

Last updated:

You will learn#

  • how to see why an import failed;
  • the refusals that come from the path, the file and the limits;
  • what to do for each.

The idea#

An import has two stages. First the server checks the path and queues the file: a bad path is refused at once. Then the ingest job reads the file with ffprobe, makes the proxy, thumbnails and audio peaks, and finishes in the state ready, or failed with a reason. The library shows the state of every asset (Waiting, Importing, Ready or Failed) and a failed one has Try again.

Quick start#

  1. Read the reason: the failed card in the library, or the CLI.
  2. Match it to the table.
  3. Fix it and import again. The same file imported twice adds nothing, because originals are kept by content.
Terminal
vukem-video media:list --project prj_7k2m9x4q1b
vukem-video media:inspect ast_4h6j8k2m3n --project prj_7k2m9x4q1b --sections probe
vukem-video doctor --full
What you seeCauseFix
E_FILE_NOT_FOUND (local mode)the path does not existcheck the path; paste the absolute path, a browser cannot read it from a dropped file
E_PATH_NOT_ALLOWEDa URL, a UNC or device path, a relative path, a .., a directory or a file that is not regulargive the absolute path of a regular file on this machine
E_PATH_NOT_ALLOWED in network modethe file is not inside VUKEM_VIDEO_IMPORT_ROOTS, or does not exist: the answer is the same on purposeask the operator to add the directory to the import roots
a file larger than 8 GiBVUKEM_VIDEO_MAX_IMPORT_BYTESraise the limit, or cut the file first
longer than 4 hoursVUKEM_VIDEO_MAX_IMPORT_SECONDSraise it, or cut the file
a frame larger than 7680 x 4320, or a side above 8192VUKEM_VIDEO_MAX_IMPORT_PIXELSscale the source down
E_FFMPEG_MISSINGno usable FFmpegsee FFmpeg, codecs and licences
E_ASSET_NOT_READY on an editthe asset is still ingestingwait for ready, then retry; it is retryable
E_RATE_LIMITEDmore than 10 imports a minutewait for Retry-After
E_QUEUE_FULLtoo many ingests at once (VUKEM_VIDEO_MAX_INGESTS)retry shortly
the file ends failed with a codec reasonthe file is damaged or in a format FFmpeg cannot readre-export the file from its source, or convert it to MP4

If the server is below VUKEM_VIDEO_MIN_FREE_BYTES (2 GiB) of free space on the workspace volume, writes are refused until you free space.

Common mistakes#

  • Importing from a network share or a removable drive that goes away: the original is copied into the workspace once, but a drive that disconnects during the copy fails the import.
  • Reading E_PATH_NOT_ALLOWED as a permissions problem in network mode. It also hides whether the file exists.

Next steps#