Reference

Error codes

Every error has a code that says what went wrong and what to do next. The same codes come from cv and from the API.

Reading an error

cv prints error: <code>: <message> on stderr, and a second line try: <targets or command> when there are suggestions. The API answers with the code in error.code and an HTTP status that follows it.

retryable is true only for the codes under Try again. See JSON and exit codes and Errors in the API.

Terminal

$ export CV_API_KEY=cv_sk_…

Set your key once. Every cv command reads it.

Terminal

$ cv convert lease.docx --to mp3

stderrexit 2error: unsupported_conversion: there is no conversion from docx to mp3try: pdf, docx, odt, rtf, docm

The file

Something about the input stops the job. cv exits 1.

Code	What it means and what to do
input_corrupted	The file could not be parsed. Check the file, and if it came from elsewhere, get it again.
input_encrypted	The file needs a password. Run again with `--password`, or the `password` option.
ocr_required	The pages are pictures with no text to read. Convert with `--opt ocr=on` to a target that takes `ocr`, and add `--opt language=<codes>` when the text is not English. `cv read` cannot recognize text, so convert to `txt` with OCR and read that.
unrecognized_format	The format of the file could not be told. Name it with `--from`, or give the file the right extension.
resource_limit	The input needs more memory, disk or pixels than a job allows, such as an image over 512 megapixels. Split it, pick fewer pages with `--pages`, or lower `--dpi`. The same request fails the same way.
not_found	The path or file id does not exist, or stdin was empty. The message names the ids that are missing. Check the path or id; uploads expire after 24 hours.
conflict	The file changed since it was read, or the request clashes with what already happened, such as an idempotency key used for another request. Read the file again and make the edits from the new view. Nothing was changed.
io_error	`cv` could not read or write a local file. Check the path, the permissions and the free space.

The request

The request cannot run as asked. Sending it again as it is fails the same way. cv exits 2.

Code	What it means and what to do
invalid_request	The request does not fit: one file was asked for and the conversion made several, the files cannot be joined into one file of the target, `--refs` was asked of a conversion without a refs view, or an input is a file whose import failed. Run the `try:` line, or pick one page with `--pages`. For a failed import, fix the URL the message names and import it again.
invalid_options	An option name or value is not valid for this conversion, or a scope names no part of the file. Use the options the message names, with the ranges from `cv targets <file> --json`. For a scope, take one from `cv read <file> --outline`.
invalid_edits	Some edits cannot be made. Fix or drop every edit the message names; `error.edits` gives each one's `reason`. Nothing was changed. See When an edit fails.
unsupported_conversion	There is no conversion from the input's format to the target. Pick a target from the `try:` line, or run `cv targets <file>`.
unsupported_elements	The file holds something the target cannot carry, or some inputs of a join cannot become its format. Change the file or pick another target. In a join, drop those inputs or convert them on their own.

The key

The request has no valid key. cv exits 3.

Code	What it means and what to do
unauthorized	The API key is missing, wrong or revoked. Set `CV_API_KEY` to a key from the dashboard. See API keys.

Try again

Something temporary went wrong. Try once more after a short wait, then report. cv exits 4.

Code	What it means and what to do
rate_limited	Too many requests: over 300 in 10 seconds for the project. Wait a second, as `Retry-After` says, and send it again.
concurrency_limit	Too many jobs of the organization are running, or too many event streams. Wait for one to end, 5 seconds as `Retry-After` says, and send it again. `cv` waits and tries again within `--wait`. If it still fails, run fewer at once.
not_ready	The uploaded file is not complete yet. Complete its upload and run again. Nothing was changed.
timeout	The job ran past its time limit. Try once more, and if it times out again, use fewer pages or a smaller file.
engine_failed	A conversion step crashed or made output that did not pass its checks. Try once more, and if it fails again, report the job id at the end of the message.
internal	The service did something it should not, and the job is not at fault. Try once more, and if it fails again, report the job id.
network_error	`cv` could not reach the service, or could not read its reply. Try once more after a short wait.

The account

An account limit stops the job. Tell the person who runs the account. cv exits 5.

Code	What it means and what to do
insufficient_balance	The balance cannot cover the job, or the job would take the project past its monthly spend limit. The message has the cost and the link to top up or to raise the limit.
too_large	The file is over the plan's size limit, or the job makes more files than the plan allows. Split or compress the file, pick pages with `--pages`, or raise the plan.
storage_limit	The organization's uploads that are still kept reach its storage limit. Delete uploads you no longer need, or wait for them to expire. It answers HTTP 403, so sending it again unchanged fails the same way.
forbidden	The API key lacks the scope the request needs, such as `jobs:write`, and the message names it. Use a key that has it; `cv` needs every scope. Or the organization is suspended and cannot upload files or start jobs, though its files and jobs can still be read. Or the request went to an address that does not serve the API.

Warnings

A job that worked can still carry warnings. Each has a code, a message, and ref or edit when it is about one place of the file or one edit. cv prints warning: <code>: <message> on stderr, and --json gives them in warnings. New codes can appear, so treat a code you do not know by its message.

Code	What it means and what to do
input_damaged	The input is damaged or cut short, and the parts that could not be read were skipped. Get a whole copy if those parts matter.
input_guessed	The input's text encoding or field separator was guessed. If the result reads wrong, save the file as UTF-8 or comma-separated first.
ocr_suggested	Some pages are pictures of text without a text layer. Convert with `--opt ocr=on` to read them.
empty	A part of the input is empty, such as a sheet, a table or a deck with no slides. Nothing to do unless you expected content there.
content_dropped	Part of the input, or of what was asked, is not in the result, such as other sheets, images, attachments or highlights. Pick a target that carries it, or accept the result.
truncated	A limit cut the result short, such as a page cap or a size budget. Ask for less, such as fewer pages, or split the file.
characters_replaced	Characters the result cannot hold were replaced with U+FFFD.
kept_as_text	Values were kept as text instead of numbers, dates or formulas. Send a formula as `formula` and a date as YYYY-MM-DD, or clean the column.
renamed	Names were changed to stay unique, such as repeated column names.
unchanged	An edit or a step changed nothing, such as an edit that gives a part the text it already has. Check the edit.
computed_on_open	The app that opens the file computes or draws this part, such as formula results, pivot tables or form scripts. Nothing to do.
uncomputed	Saved formula results are missing or may be out of date. Open and save the file in a spreadsheet app, then read it again.
not_editable	Some parts cannot be edited here, such as text with tracked changes, a signed PDF, content controls or text boxes. Leave them out of the edits.
line_breaks	Each `\n` in a value for one paragraph became a line break. Add paragraphs with `insert`.
refs_moved	The edits moved refs, so the edited file has no rev. Send the next edits to the original in the same list, or read the edited file again.
more_warnings	More warnings were left out of the list.

Updated 3 November 2026