Troubleshooting.
When something does not work.
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 channelsmith or journalctl -u channelsmith.
01The server does not start: "This database was last used by Channelsmith X, but this code is Y"
You started an older version on data a newer version already used. Install version X or newer. Or restore a backup made with version Y into an empty DATA_DIR (Backups).
02"Chrome not found" or renders fail at once
Install Google Chrome or Chromium (Install), or set CHROME_PATH in .env to its program file and restart. In Docker, Chromium is in the image already.
03"ffmpeg not found"
sudo apt install ffmpeg, or set FFMPEG_PATH in .env.
04Renders are slow or wait long in the queue
System health shows the speed of the last render. 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 prints a new one (First steps).
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. Once it works, Stripe retries the failed events by itself.
11The API answers 401, 402 or 403
401: the key is wrong or revoked. 402: the workspace's plan does not include the API (Plans). 403: the API is off (Settings, Public API).
12Webhooks 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.
13The 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). Tool 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.
14"Connect YouTube" fails with redirect_uri_mismatch
The redirect URI of your Google OAuth client must be exactly your public URL plus /api/youtube/callback, with https and without a trailing slash. Check Settings, Server, "Public URL" too (Publishing to YouTube).
15Every upload ends up private
Google locks uploads from API projects it has not audited to private. Apply for the YouTube API Services audit; until then publish from YouTube Studio by hand after the upload.
16People must connect YouTube again every week
Your OAuth consent screen is still in Testing, where Google ends sign-ins after about seven days. Publish the consent screen.
17"The YouTube API quota of your Google project is used up for today"
One upload costs 1,600 of the default 10,000 daily units. Retry tomorrow, or ask Google for more quota with the audit form.
18"Wikimedia Commons asks to wait …" on the Footage step
Wikimedia limits how fast one server may download. The studio stops asking until the time it names has passed; run Footage again then. Setting the public URL (Settings, Server) lets Wikimedia identify your server, as its policy asks.
19A render stopped part-way
A frame that hangs is tried again on a fresh page; if it keeps failing the render stops with a message naming the frame. Finished parts are kept: rendering again continues where it stopped instead of starting over, as long as the storyboard did not change.
20A footage scene has no clip
No source returned a usable file for its query. Open the episode's Footage step, search with other words or pick an upload. Without Pexels or Pixabay keys only Wikimedia Commons is searched, which has far less video.
21An episode step failed
The episode shows the step's error and its credits are refunded; run the step again. The console's Episodes page lists failed steps of every workspace with their errors. A step that was running when the server restarted is marked failed on start and can be run again.
22The research step finds no sources
Web search is off (Settings, Channels and publishing) or the Anthropic account has no web search access. People can still add links and notes to the episode; research then uses only those.
23npm run upgrade-check says "The server is not built"
Run npm run build first (or use the Docker image, which has the build).