Troubleshooting
common messages and fixes.
Most problems show up as a line in the server log, a red status check in the console, or a reason in the app's not-checked list. Find the message below.
01Status says "this server needs Node 26 or later"
The server needs Node.js 26. Run node --version; with nvm, run nvm install 26 and nvm use 26 in the top folder of the download (it has an .nvmrc). npm also warns about the engine during npm ci on an older Node.js.
02npm ci prints warnings about install scripts or vulnerabilities
npm 11 lists packages whose install scripts are "not yet covered by allowScripts" and reports moderate findings. Both are notices: the install completes, and the findings are in development-only packages (npm audit --omit=dev reports 0 vulnerabilities in what the server runs, checked on 12 November 2026). Do not run npm audit fix --force: it changes development tools to versions with breaking changes.
03npm ci stops with a c2pa message
- Fingerprint does not match: the downloaded Content Credentials reader is not the official file for your system. Delete
node_modulesand runnpm ciagain on a clean network. Do not bypass the check. - Warning that no reader exists for this system (for example Alpine Linux): the server still runs, and Content Credentials are listed as not checked. Use a Debian or Ubuntu based server or image to get them.
04"ADMIN_SECRET_KEY is not set"
The server generated its own key in admin-secret.key next to the database. It works, but set ADMIN_SECRET_KEY in .env and back it up before going live. If you change the key later, enter every provider key again.
05"PUBLIC_BASE_URL is not set", "PUBLIC_BASE_URL must be …" or sharing fails
Set PUBLIC_BASE_URL to the server's public https address, for example https://checks.yourcompany.com, without a user name, query or #, and restart. A value the server cannot use stops the start with "PUBLIC_BASE_URL must be the server's public http or https address".
06I lost the console setup code
Restart the server: as long as no owner exists, each start prints a new setup code, and any printed code works until the owner is created. Or set ADMIN_SETUP_TOKEN in .env and use that.
07The server does not start because of the upload folder
The server refuses to start when its upload folder under the system temp folder belongs to another user or can be opened by others. This happens when the server once ran as another user. Delete that folder (it holds only temporary uploads) or start the server as the user that owns it.
08Every audio or video check says "The length of this file could not be read"
ffprobe is missing on the server. Install ffmpeg (sudo apt-get install ffmpeg), or add it to the Docker image (see Deployment), and restart. The console's Status page shows "ffmpeg and ffprobe installed".
09Uploads fail with "too large", 408 or 429
- 413, too large before the server answers: your reverse proxy limits request bodies; allow your largest file cap plus 1 MB (Uploads). From the server itself: the file is over the cap of its kind in Media caps and thresholds.
- 408: the upload stalled for 15 seconds or ran past its deadline; a slow connection on a large video. Try again on a better connection.
- 429, too many uploads at once: one install may upload one file at a time, one address two, and the server eight in all (
UPLOAD_MAX_CONCURRENT).
10The app shows "not checked"
| Reason shown | What to do |
|---|---|
| not configured | Turn the service on in the console and add its key (and model, where it has one). |
| provider error | Press Test connection in that service's section; check the key, billing and quota at the provider. |
| busy | The provider was slow or limited the request, or the check ran out of time. Try again later. |
| daily limit reached | The person used their allowance, or a cap over all installs was reached (console, Plans). |
| not available on this server | A tool is missing on the server, for example ffmpeg or the Content Credentials reader. See the status checks. |
| no data | The source had nothing to say, for example a registry that answered without a registration date. |
"AI read: not configured", "Screenshot read: not configured" and "Claim extraction: not configured" all mean the language model is off or has no model and key.
11Messages never get Safety OK
Local phrase rules alone never give OK. Set up the language model; with it, a message with no warning signs can reach OK.
12The app stops at start with "API_BASE_URL must be the server origin"
The address you passed with --dart-define=API_BASE_URL= has a path, query or user name. Use only the scheme, host and optional port, for example https://checks.yourcompany.com.
13The Android emulator cannot reach the server
On the emulator, your computer is 10.0.2.2, not localhost. Use http://10.0.2.2:8787 while testing.
15Users are asked for consent again
That is intended after you switch a service on or off, change a vendor, or move a provider to another host: the consent covers the exact services it named. See Consent.
16Pro does not show in the app
Pro shows only when Plans → Pro plan is on and the product ids of that platform are set in Store. On a device, the store must also know the product; on iOS test with a sandbox account.
17No banner ads appear
1.0.0 ships no ad package, so no banner appears until you add one (see Console, Money).
18Everyone hits the rate limit at once
TRUST_PROXY_HOPS is probably 0 behind a proxy, so every request looks like it comes from the proxy. Set it to the real number of proxies you control.