# An import fails

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

Source: https://alexgalhardo.github.io/vukem-video/docs/troubleshooting/import-fails/

## 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.

```bash
vukem-video media:list --project prj_7k2m9x4q1b
vukem-video media:inspect ast_4h6j8k2m3n --project prj_7k2m9x4q1b --sections probe
vukem-video doctor --full
```

| What you see | Cause | Fix |
| --- | --- | --- |
| `E_FILE_NOT_FOUND` (local mode) | the path does not exist | check the path; paste the absolute path, a browser cannot read it from a dropped file |
| `E_PATH_NOT_ALLOWED` | a URL, a UNC or device path, a relative path, a `..`, a directory or a file that is not regular | give the absolute path of a regular file on this machine |
| `E_PATH_NOT_ALLOWED` in network mode | the file is not inside `VUKEM_VIDEO_IMPORT_ROOTS`, or does not exist: the answer is the same on purpose | ask the operator to add the directory to the import roots |
| a file larger than 8 GiB | `VUKEM_VIDEO_MAX_IMPORT_BYTES` | raise the limit, or cut the file first |
| longer than 4 hours | `VUKEM_VIDEO_MAX_IMPORT_SECONDS` | raise it, or cut the file |
| a frame larger than 7680 x 4320, or a side above 8192 | `VUKEM_VIDEO_MAX_IMPORT_PIXELS` | scale the source down |
| `E_FFMPEG_MISSING` | no usable FFmpeg | see [FFmpeg, codecs and licences](/docs/self-hosting/ffmpeg-and-licences) |
| `E_ASSET_NOT_READY` on an edit | the asset is still ingesting | wait for `ready`, then retry; it is retryable |
| `E_RATE_LIMITED` | more than 10 imports a minute | wait for `Retry-After` |
| `E_QUEUE_FULL` | too many ingests at once (`VUKEM_VIDEO_MAX_INGESTS`) | retry shortly |
| the file ends `failed` with a codec reason | the file is damaged or in a format FFmpeg cannot read | re-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

- [Media library](/docs/guide/media-library)
- [The diagnostic bundle](/docs/troubleshooting/diagnostic-bundle)
