Skip to content

Troubleshooting

Common problems

The errors people meet most, what each one means and which page fixes it.

Last updated:

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#

  1. Find the code in the table below.
  2. Follow its fix, or the page it links.
  3. If the problem stays, run vukem-video doctor --full and read the checks that fail, then make a diagnostic bundle.
CodeWhat it meansFix
E_WORKSPACE_LOCKEDanother process owns the workspace and cannot be reachedThe workspace is locked
E_FFMPEG_MISSINGno usable FFmpeg, or a required encoder, filter or muxer is missingFFmpeg is not found
E_NO_ENCODERno H.264 encoder passed the test encodeNo H.264 encoder works
E_UNAUTHORIZEDthe token, key or session is missing or invalidin 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_FORBIDDENthe key lacks the scope, or is limited to another projectcreate a key with the scope the call needs
E_REVISION_CONFLICTthe project changed since your base_revisionread the project again, rebuild the batch and resend; see Batches and revisions
E_ASSET_NOT_READYthe asset is still ingestingwait for ready, then retry
E_PATH_NOT_ALLOWED, E_FILE_NOT_FOUND, E_UNSUPPORTED_MEDIA, E_LIMIT_EXCEEDEDan import was refusedAn import fails
E_LINT_BLOCKINGan export was refused because lint found errorsrun vukem-video lint, fix the findings in details.findings, export again
E_QUEUE_FULL, E_RATE_LIMITEDa concurrency or rate limit is reachedwait (the answer carries Retry-After for the rate limit) and retry; see Jobs
E_EXPORT_FAILED, E_VERIFY_FAILEDthe export process failed, or its file did not pass verificationread details.reason or details.checks, then Export is slow and the diagnostic bundle

Common mistakes#

  • Retrying an error that is not retryable. A E_VALIDATION or E_LINT_BLOCKING gives the same answer until you change the request.
  • Reading only the message. The hint and details say what to change.
  • Deleting files in the workspace to fix a problem. Nothing there is safe to remove by hand; use vukem-video doctor --gc for what no project refers to.
  • Reporting a bug without the version. Run vukem-video version and attach the diagnostic bundle, which is cleaned of secret values and holds a project document only when you ask for it.

Next steps#