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.
Exit codes
Section titled “Exit codes”| 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.
Messages the CLI prints before any upload
Section titled “Messages the CLI prints before any upload”| 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.
Messages while waiting for the result
Section titled “Messages while waiting for the result”| 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.
Git history warnings
Section titled “Git history warnings”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. |
Errors from the CI API
Section titled “Errors from the CI API”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.