You will learn#
- how to read an error: its code, its hint and whether it is retryable;
- the most common errors, with their cause and fix;
- how to collect what a bug report needs.
The idea#
Every failure has a stable code that starts with E_, a message, a hint and a retryable flag. The CLI prints them, and returns them as fields with --json; the HTTP API returns them as fields, and the MCP server in an error result. A retryable error is safe to repeat after a short wait; the CLI exits with 2 for it and with 1 for a failure that retrying will not fix. The full list is in the error codes reference.
Quick start#
- Find the code in the table below.
- Follow its fix, or the page it links.
- If the problem stays, run
vukem-video doctor --fulland read the checks that fail, then make a diagnostic bundle.
| Code | What it means | Fix |
|---|---|---|
E_WORKSPACE_LOCKED | another process owns the workspace and cannot be reached | The workspace is locked |
E_FFMPEG_MISSING | no usable FFmpeg, or a required encoder, filter or muxer is missing | FFmpeg is not found |
E_NO_ENCODER | no H.264 encoder passed the test encode | No H.264 encoder works |
E_UNAUTHORIZED | the token, key or session is missing or invalid | in local mode the token is in <workspace>/token (vukem-video token:rotate makes a new one); in network mode sign in or use an API key |
E_FORBIDDEN | the key lacks the scope, or is limited to another project | create a key with the scope the call needs |
E_REVISION_CONFLICT | the project changed since your base_revision | read the project again, rebuild the batch and resend; see Batches and revisions |
E_ASSET_NOT_READY | the asset is still ingesting | wait for ready, then retry |
E_PATH_NOT_ALLOWED, E_FILE_NOT_FOUND, E_UNSUPPORTED_MEDIA, E_LIMIT_EXCEEDED | an import was refused | An import fails |
E_LINT_BLOCKING | an export was refused because lint found errors | run vukem-video lint, fix the findings in details.findings, export again |
E_QUEUE_FULL, E_RATE_LIMITED | a concurrency or rate limit is reached | wait (the answer carries Retry-After for the rate limit) and retry; see Jobs |
E_EXPORT_FAILED, E_VERIFY_FAILED | the export process failed, or its file did not pass verification | read details.reason or details.checks, then Export is slow and the diagnostic bundle |
Common mistakes#
- Retrying an error that is not retryable. A
E_VALIDATIONorE_LINT_BLOCKINGgives the same answer until you change the request. - Reading only the message. The hint and
detailssay what to change. - Deleting files in the workspace to fix a problem. Nothing there is safe to remove by hand; use
vukem-video doctor --gcfor what no project refers to. - Reporting a bug without the version. Run
vukem-video versionand attach the diagnostic bundle, which is cleaned of secret values and holds a project document only when you ask for it.