From a symptom to its cause and fix, with the messages CirCI prints, for installs, uploads, builds, mail, sites and TLS.
Start with docker compose exec circi circi admin doctor: it checks storage, the database and its migrations, mail, disk space, the dashboard address and the cookie scope of the domains, and prints a fix: under each warning. Instance › Health shows the same checks. Then find the symptom below. The server's log (docker compose logs circi) has the rest: see Monitoring.
Invalid configuration: followed by a list, and exit code 1
An environment variable is missing or malformed. Each line names the variable. Fix it and start again. The common ones are below.
S3_BUCKET: required when STORAGE_DRIVER=s3
Set S3_BUCKET. With S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY, set both, or neither to use the default AWS credential chain (an IAM role). See Storage.
AUTH_GITHUB_CLIENT_ID / AUTH_GITHUB_CLIENT_SECRET: set both, or neither (also GitLab, Google)
A sign-in provider needs its ID and its secret together.
AUTH_OIDC_ISSUER / AUTH_OIDC_CLIENT_ID / AUTH_OIDC_CLIENT_SECRET: set all three
The OIDC provider needs all three. The issuer must be an http(s):// address.
PREVIOUS_PUBLIC_URLS: <host> is the current PUBLIC_URL host
Remove the current host from PREVIOUS_PUBLIC_URLS.
Log warning PUBLIC_URL uses plain http on <host>. Logins need https outside local development
Put a TLS proxy in front and set PUBLIC_URL to the https address: TLS and reverse proxy.
/readyz answers 503
The checks object in the answer shows which of database or storage is fail. The log has readiness check failed with the error. The doctor's Database or Storage line says what to check.
Doctor: Database: Not reachable: …
Check DATABASE_URL and that Postgres is running.
Doctor: only N of M migrations are applied
Run circi migrate, or restart: the server migrates on start unless --no-migrate is set. See Upgrades and migrations.
Doctor: Migrated by a newer version of CirCI
Something ran a newer version against this database. Run the same version everywhere, or roll the database back from a backup (Backups).
Doctor: Storage: Not usable: …
S3: check S3_BUCKET, S3_ENDPOINT, the credentials and that the bucket exists. Local disk: check that STORAGE_PATH exists and the server may write to it.
Doctor: Disk space: The storage disk is running low
Less than 10% or 2 GB is free. Free space with circi admin storage gc, lower the projects' retention, grow the volume or move to S3: Retention and garbage collection.
That setup code is wrong. Find it in the server log.
The first account needs the setup code. It's logged at start (No accounts yet. Open … with the setup code …), or circi admin setup-code prints it. The setup pages answer "Not found" once an account exists.
No email arrives: sign-in codes, invitations, notifications
SMTP isn't set up or doesn't accept the login. The doctor's Mail line says which (SMTP_HOST is not set, or Did not accept the connection: …). circi admin mail test --to <address> sends a real test message. With AUTH_EMAIL_ENABLED=true and no SMTP, email sign-in stays off. See Configuration.
Too many sign-in codes requested for this address. Try again later.
Code requests are limited per address, whether or not it has an account: 5 per 15 minutes.
Signing in works, then you're signed out, or the cookie is dropped
PUBLIC_URL is plain http on a real host. Sign-in cookies need https.
Behind a proxy, everyone shares one rate limit
TRUSTED_PROXIES isn't set, so every request appears to come from the proxy's address. Set it to the proxy's address or range. See TLS and reverse proxy.
A "moving to" banner after changing PUBLIC_URL
Expected: the startup log says The dashboard address changed from … to …. Finish the checklist on Instance › Health; a few registrations outside CirCI, such as the GitHub App's webhook, still name the old address.
circi upload prints one line, error: …, and exits 2. Run it again with --debug (or DEBUG=1) for the stack trace. The exit codes are in The CLI, and every error message in Errors and exit codes. The size and count limits are in Limits.
Message
Cause and fix
The server refused the token (…). Check that CIRCI_TOKEN is this project's CI token.
A 401 or 403: the token is wrong, belongs to another project, or was rotated. Copy the current one from the project's settings.
… Check CIRCI_API_URL.
The server couldn't be reached from the CI job: check the address, DNS and the proxy.
Couldn't run git. Is it installed and on PATH?
The upload reads git history. Install git in the CI image, or pass the commit and branch explicitly (CI examples).
No such directory: ./screenshotz
The folder doesn't exist. Only *.png files are uploaded, and hidden folders and node_modules are skipped.
Too many open files. Raise the limit (ulimit -n) and retry.
A large upload hit the job's file limit.
Files are limited to 26214400 bytes (HTTP 413)
One file is over 25 MiB.
N file(s) weren't uploaded or failed verification (HTTP 409)
The server's check of the uploaded files found some missing or corrupt. The CLI sends them again (N files didn't arrive; sending again). If it keeps failing, check the storage and any proxy that limits request bodies.
Invalid build name "…": use letters, digits, ".", "_" or "-" (max 64)
The --name isn't valid.
Invalid commit SHA "…"
The commit isn't 7 to 64 hex characters.
parallel.total must be between 1 and 1000
A bad --shard.
Build not found (HTTP 404)
The build ID doesn't belong to this project's token.
The build stays in Uploading and then fails: Timed out waiting for N of M shard(s): shard 3. The CI job(s) that should have uploaded them probably failed or never ran.
A shard never arrived. After UPLOAD_TIMEOUT_MINUTES (default 60) the build fails and names the missing shards. Re-run the failed job. A build whose job stopped early says The upload never finished: the CI job stopped before sending the screenshot list.
Site uploads (circi site upload, circi storybook upload) have their own refusals:
Message
Cause and fix
Static site hosting isn't set up on this server
The server has no STATIC_SITES_HOST.
Static site hosting is off for this project: turn it on in the project settings
Switch on Host static sites in the project.
Send the site as application/gzip (a .tar.gz)
Use the CLI, or send a gzip tarball.
The archive contains no files
The folder was empty.
A <kind> needs <entry> at its top level
A typed site, such as a Storybook, needs its entry file at the root of the folder you upload.
The worker isn't running or is busy. circi serve runs only HTTP: a split install needs a circi worker too (circi all runs both). Look at Background jobs on Instance › Health: the oldest waiting job keeps getting older, and the log shows could not claim a job if the worker can't read the queue. See Scaling the worker.
N screenshots couldn't be read and --wait exits 2
The server couldn't decode a file. Each is listed with the reason, for example Couldn't read this image: …. Check that the file is a complete PNG. See How a build flows.
Every screenshot is Added on a build that has a baseline
The screenshot names changed, or the build name differs: a screenshot is compared with the baseline of the same name in a build of the same name. A screenshot's name is its path under the upload folder without .png. See Baselines.
Everything shows as changed on the first build of a project
A first build has nothing to compare with, so every screenshot needs review, even on the default branch.
A build page says it fell back to the default branch's newest build
The history wasn't available: a shallow checkout the CLI couldn't deepen, or --no-fetch. See The CLI.
Slow comparisons, or the worker runs out of memory
Check the diff engine and its threads, or give the worker more memory: Performance and Scaling the worker. A job that keeps killing its worker is failed after its lease expires too many times (lease expired too many times).
The project isn't linked to a repository. A job for an unlinked project is skipped with project is not linked to a repository. Check the repository in the project's settings, and that the app or token can reach it.
The integration shows Needs attention
The host removed the installation or rejected the token. Nothing is queued for it until you reconnect or reinstall. See Integrations.
Commands such as /circi approve do nothing
The commenter's host account must belong to exactly one member of the workspace. CirCI matches by account ID, never by email.
The webhook from the host is refused
The signature or token didn't verify: GitHub's secret is the App's; GitLab's and Bitbucket's are shown on the integration's page.
Site not found: "No site is published at this address. It may have expired, or the link is wrong."
The address names a site that was never published or has been removed. Check the address against the upload's output.
Site expired: "This site was removed once it was older than the retention period."
Publish it again. Sites follow the project's retention. See Hosted sites.
A custom domain gets no certificate
Caddy asks GET /internal/tls-ask?domain=<host> and only a verified custom domain answers 200. The proxy must be able to reach the server's internal path. See Site domains.
Doctor: Sets cookies for a whole domain
Another host on the domain sets cookies for the whole domain, and they would reach the dashboard. Make that host's cookies host-only (no Domain attribute).
Doctor: Serves content at its apex
The sites domain must serve nothing at its own name, only the sites under its subdomains.
Wildcard certificate fails
The sites domain's wildcard needs the DNS challenge (DNS-01); the bundled Caddy covers it. See TLS and reverse proxy.