Skip to content

Reference

Errors and exit codes

What every exit code of circi upload means, the messages the CLI and the CI API print, and what to do about each.

A CI job sees a failure in two places: the exit code of circi upload, and the one-line error: message it prints. Both come from the CLI, which relays what the CI API answered. For the endpoints themselves, see the CI API reference.

Command Code Meaning
circi upload 0 The upload succeeded. With --wait: the build passed, or the git host's check is the merge gate and the job doesn't fail on changes.
1 With --wait: visual changes need review and this job is the gate. Approve them in the dashboard, then re-run the job.
2 An error. Bad flags or setup, the server couldn't be reached, the build failed to process or had screenshots it couldn't read in a project that blocks merges, or --wait timed out.
circi site upload, circi storybook upload, circi argos-env 0 / 2 Done, or an error (printed as one line).

An error before the upload finishes (code 2) comes with a line error: <message>. An error that is a bug rather than a mistake of yours also prints (Run again with --debug, or set DEBUG=1, for the stack trace.); with --debug the stack follows the message.

A build that failed to process or that holds unreadable screenshots exits 2 only when the project blocks merges. In a project that doesn't, the job exits 0 and prints a warning: line. The server's reason is printed either way. See How a build flows.

With --wait, a build whose result is pending is polled until it isn't, first every 0.5 seconds and then every 2 seconds at most, until --timeout (default 600 seconds). If the server can't be reached while waiting, the CLI prints warning: <reason>; still waiting once and keeps polling until the timeout.

Message Cause and fix
Set CIRCI_TOKEN to the project CI token No CIRCI_TOKEN in the environment. Add the project's token as a CI secret.
Set CIRCI_API_URL (or --api-url) to your CirCI address Neither the variable nor the flag is set.
--timeout must be a positive number of seconds The value isn't a number above zero.
--gate must be "status" or "exit-code" Any other value.
--shard must look like 1/4 or --shard must look like 1/4: this job's number, then how many jobs there are The shard isn't n/total, or n is outside 1 to total.
Could not tell which CI run these shards belong to. Set CIRCI_PARALLEL_NONCE (or --nonce) to the same value in every shard. A sharded upload on a CI the CLI doesn't recognize.
Could not determine the commit. Run inside a git checkout or set CIRCI_COMMIT. Not in a git checkout and no CIRCI_COMMIT.
No such directory: <dir>, <dir> is not a directory The folder argument is wrong.
No .png files found in <dir> The folder holds no PNG, or only hidden folders and node_modules.
<path> is 31.2 MB; the limit is 25 MB per screenshot A screenshot over 25 MB.
<path>.json isn't valid JSON (…), <path>.json must contain a JSON object The metadata file next to a screenshot is broken.
<dir> contains symbolic links or special files, which hosted sites can't have: … circi site upload refuses links and special files; the first five are named.
Couldn't run git. Is it installed and on PATH? The CLI needs git.
Too many open files. Raise the limit (ulimit -n) and retry. The operating system's file descriptor limit.
No such file or directory: <path>, Not a directory: <path>, Is a directory, not a file: <path>, Permission denied: <path> A file problem on the CI machine, named by path.

Messages about reaching or being refused by the server

Section titled “Messages about reaching or being refused by the server”
Message Cause and fix
Couldn't reach https://ci.acme.io (connection refused) followed by Check CIRCI_API_URL. The server isn't reachable. The detail can be host not found, connection reset, timed out, certificate expired, self-signed certificate or not a valid URL. Check the address, the proxy and the certificate.
The server refused the token (…). Check that CIRCI_TOKEN is this project's CI token. The server answered 401 or 403. The token is wrong, belongs to another project, or was rotated or deleted with the project. The text in parentheses is the server's own.
The server failed: … (HTTP 502) A 5xx answer after the retries. See the server log.
Upload of 3fa9c1d20b4e failed: 413 … One file couldn't be sent; the first 12 characters of its hash say which. The server's reason follows.
Server asked for unknown file <sha256> The server asked for a file the CLI didn't offer. Report it.
<n> files didn't arrive; sending again Not an error: finalizing reported missing files and the CLI sent them again once. If finalizing then fails again, the message is the server's.

Every API call is retried up to 4 times in all, with waits of about 0.5, 1 and 2 seconds (each scaled by a random 50 to 100 percent), after a network failure, a 429 or any 5xx answer. A request times out after 30 seconds, and a file or site upload after 2 minutes. 400, 401, 403, 404, 409, 413, 415 and 422 aren't retried: they won't change. Every call the CLI makes is safe to repeat.

Message Meaning
error: timed out waiting for the build to be processed --timeout ran out. Exit 2. The build keeps processing; look at it in the dashboard, or raise --timeout.
error: Build #12 failed to process: <reason> The pipeline failed. The line after it is Details: <build url>.
error: <screenshot name>: <reason> and Upload the build again with valid PNGs: <url> A screenshot couldn't be read, for example because it isn't a valid PNG. One line per screenshot.
Review the changes at <url> and After approving, re-run this job to unblock the merge: <job url> Exit 1. The job is the gate.
warning: <text> after the summary The build passes, but something needs a look; for example merges aren't blocked for this project.

The summary line reads <outcome>: N changed, N added, N removed, N unchanged, with , N couldn't be read when some are unreadable. The outcomes are listed in the CI API reference.

The CLI collects the history CirCI uses to choose a baseline. When it can't, it prints warning: <reason>. CirCI will compare against the latest <default branch> build instead. and the upload carries on.

Reason Fix
Not inside a git repository Run in a checkout.
Commit <sha> is not available locally The checkout lacks the head commit.
Could not read the commit history (shallow clone) Deepen the checkout.
Base branch "<name>" is not available from origin Fetch the base branch, or check CIRCI_BASE_BRANCH.
No common history with "<name>" within 2000 commits; use a deeper checkout (e.g. fetch-depth: 0) Use a full clone, or a deeper one.

The reply is { "error": "…" }, with fields on validation failures; see Conventions.

Status When What to do
400 The request is invalid. Messages are plain sentences about a field ("Commit sha isn't in the right format", "Branch must be 255 characters or fewer"), or one of: Invalid build name "<name>": use letters, digits, ".", "_" or "-" (max 64), Invalid commit SHA "<sha>", ancestorShas must be at most 2000 commit SHAs, parallel.total must be between 1 and 1000, Invalid screenshot name "<name>", Duplicate screenshot name "<name>", The archive contains no files, A <kind> needs <entry page> at its top level (for example A Storybook needs index.html at its top level), or a message about an unsafe site archive. Fix the request.
401 A valid project token is required (Authorization: Bearer circi_…). Send the project's CI token.
403 Static site hosting is off for this project: turn it on in the project settings. Turn Host static sites on.
404 Build not found; This file wasn't requested by any build (POST /v1/builds first); Static site hosting isn't set up on this server. The build isn't in this project; create the build first; set STATIC_SITES_HOST.
409 N file(s) weren't uploaded or failed verification with missing; Build #N is already <status>; it can't take more screenshots; Another shard of this build already uploaded a screenshot with one of these names. Send the missing files and finalize again; upload a new build; use unique names across shards.
413 Files are limited to 26214400 bytes, or a hosted site over a limit (see Limits), or a JSON body over 16 MB. Shrink the file, or split the build.
415 Send the file as image/png or application/octet-stream; Send the site as application/gzip (a .tar.gz). Fix the content-type.
422 The uploaded bytes hash to <hash>, not <hash>. The file changed or was damaged in transit; send it again.
500 Internal server error. See the server log.

On the Argos-compatible /v2, a build with files not uploaded answers 400 instead of 409, and screenshots that aren't PNG are refused with CirCI compares PNG screenshots; "<type>" isn't supported.