Troubleshooting
the usual problems and their fixes.
Start with the console's System health page: it shows Chrome, ffmpeg, free disk, the queue and missing keys. The server log has the details of every error: docker logs kinetica or journalctl -u kinetica.
01The server does not start: "This database was last used by Kinetica X"
You started an older version on data a newer version already used. Install version X or newer, or restore a backup made with your version into an empty DATA_DIR (Restore).
02"Chrome not found", or renders fail at once
Install Google Chrome or Chromium (Installation), or set CHROME_PATH in .env to its program file and restart. In Docker, Chromium is in the image already. The console's status check "Chrome and ffmpeg are installed" is a blocker until both are found.
03"ffmpeg not found"
sudo apt install ffmpeg, or set FFMPEG_PATH (and FFPROBE_PATH) in .env.
04Renders are slow or wait long in the queue
System health shows the speed of the last render. In Settings, Rendering: "Renders at the same time" (each needs about one CPU core and 600 MB of memory) and "Chrome pages per render". Plans with a higher queue priority go first; each workspace runs one render at a time by default so one customer cannot block the others.
05Disk almost full
System health warns under 5 GB and under 1 GB free. Console, Storage shows who uses what. Settings, Rendering, "Delete render files after (days)" removes old render files. Old backups: npm run backup -- --keep 7.
06The saved API keys stopped working after a move or restore
ADMIN_SECRET_KEY is different from the one the keys were saved with. Put the old key back into .env, or enter the keys again under Settings, Integrations.
07Lost the console owner password
node --env-file=.env dist/src/server/recover-owner.js you@agency.com on the server, in the Kinetica folder, prints a new one; add --reset-2fa to remove two-factor too (First steps). Run it from the Kinetica folder or set DATA_DIR; otherwise it answers "No console database at …".
08No e-mails arrive
Both the Resend key and Settings, E-mail, "Sender" are needed, and the sender's domain must be verified in Resend. Until then the console (Users) and the studio (Team) show invite links to copy and send yourself.
09A customer paid but has no plan or credits
The Stripe webhook is missing or its signing secret is wrong (Stripe webhook). Stripe's dashboard shows each delivery and the answer it got; "Webhook secret not set" means the secret is not entered. Once it works, Stripe retries the failed events by itself.
10Invite, share or review links point to the wrong address
Set Settings, Server, "Public URL" (or PUBLIC_URL in .env) to the https address people use.
11"The AI director is not set up on this server"
No Anthropic key is set. Add it under Settings, Integrations and press "Test". Until then people build videos by hand, and every AI tool is shown switched off with a note.
12Videos render without a narrator
No ElevenLabs key is set, Settings, Voice, "Voiceover" is off, or the workspace's plan has no voiceover. Captions still follow the text.
13An upload fails
Images up to 15 MB, music up to 30 MB, MP4 clips up to 200 MB, and 2 GB per workspace in total. A larger file through Caddy needs the request_body max_size line from Installation. "The file's contents do not match its type" means the file is not what its extension says, or an SVG contains scripts.
14The API answers 401, 402 or 403
401: the key is wrong or revoked. 402: the workspace's plan does not include the API, or it has too few credits. 403: the API is off (Settings, Public API).
15Webhooks are not delivered
The URL must be https on port 443 and reachable from the internet; local and private addresses are refused. The Developers page lists the last deliveries and their result, and has a "Test" button.
16The MCP server shows no tools
Check the path to the file and that Node.js 22+ is installed. Started with npm, it needs npm run -s mcp (the -s matters). Answers that start with "STUDIO_URL is not set" or "STUDIO_API_KEY is not set" mean the env block of the config is missing.
17npm run upgrade-check says "The server is not built"
Run npm run build first (or use the Docker image, which has the build).