Troubleshooting
OpenShorts self-host failures, and the variable that fixes each
Nine problems that show up after docker compose up — slow renders, YouTube bot checks, wrong-language captions, rate limits, disk growth — each mapped to the setting to change first.
Start with the logs, not with the settings
Two things tell you where a failure lives: docker compose logs -f backend shows what the service did, and DEBUG_LOGS=true puts the full pipeline log — yt-dlp, ffmpeg, model output — in the dashboard where the failure actually happened. Set that flag first; most of the nine problems below are diagnosed from it in under a minute.
1. The dashboard will not load
The dashboard is on 5175, not 5173, because the compose file maps container port 5173 out to 5175. If nothing answers there, check the stack before you check the app:
docker compose ps
docker compose logs -f frontend
If 5175 is already in use on your machine, change the left-hand side of the port mapping (5176:5173) and restart. If the containers exited instead of running, the cause is usually a missing .env or a build that never finished. The install guide has the full port and volume map if you want to know which container is supposed to answer on what.
2. A short video takes forever
On CPU the project's own figure is 5 to 8 minutes of processing for an 8-minute video. That number is the pipeline doing transcription and facial tracking frame by frame — it is not a bug, and no setting will turn a CPU box into a GPU one. Which flags to flip (WHISPER_MODEL, FFMPEG_ENCODER, TRANSCRIBE_BACKEND) and how to make the GPU visible to the containers is on the install guide; it is not repeated here.
What belongs on this page is the case that edit does not fix: it runs fine on short videos and dies at the render stage on long ones. That is memory, not speed. Watch the backend container while a long video runs, and remember the models themselves take a few gigabytes before the first frame is processed.
3. YouTube links fail, or the source is rejected
Two different things get blamed on the same button:
Bot detection. YouTube throttles anonymous downloads from datacentre and VPS IPs. YOUTUBE_COOKIES takes Netscape-format cookies exported from a logged-in browser session and gets the download through. Treat that cookie jar like a password, because it is one.
The quality gate. QUALITY_GATE_MIN_HEIGHT defaults to 720 and warns before processing a YouTube source below that height. It only applies to URL sources, not uploads. Setting it to 0 disables it — useful for archival footage, risky for anything you want to look good in vertical.
4. Captions are wrong, missing, or in the wrong language
Whisper guesses the language from the audio, and a noisy multi-speaker podcast or an interview with background music is exactly where it guesses wrong. Raise WHISPER_MODEL to small before you go higher, and check WHISPER_DEVICE / WHISPER_COMPUTE match your hardware — cuda with float16 on a GPU, cpu with int8 without one. Mixing those two is the most common reason a model appears to load and then produces nonsense.
If the captions are simply missing rather than wrong, the pipeline never got past transcription: look for the model download in the backend log, which is where a failed first-run fetch shows up.
5. Your own instance returns rate-limit errors
The backend ships with rate limiting on by default, sized for a personal instance: authentication, processing and MCP endpoints each have their own window and budget. If you are the only user and you keep hitting it — or you scripted a batch of clips through the API — set RATE_LIMIT_ENABLED=0, or raise the specific limit instead of turning the whole thing off.
If you run it behind a reverse proxy, FORWARDED_ALLOW_IPS must name your proxy's address. Leaving it wide open lets any client claim any IP, which defeats the limiter completely. The MCP page has the per-endpoint budgets and the errors a client sees when it exceeds them.
6. Disk usage climbs without limit
The compose file bind-mounts ./output from your clone, so every clip, thumbnail and intermediate file lands on your host. Several retention settings exist for exactly this: thumbnail retention, actor-upload retention, and the TTLs on media URLs and tokens. If you want clips off the machine entirely, the S3 settings (AWS_*, including a separate public bucket) mirror output to object storage. Otherwise, put a cron job on ./output and be brutal about it.
What is safe to delete is easiest to see from what the pipeline writes: the MP4s are yours to keep, and the rest is scratch. Finished job records are cleaned out of the queue an hour after they finish, so an empty job list does not mean empty disk.
7. Clips are reachable by anyone who has the link
Media URLs are signed and time-limited rather than permanent public paths, which is why MEDIA_TOKEN_TTL_SECONDS and MEDIA_URL_TTL_SECONDS exist. Lower them if you share links in public places. If you expose the instance on the open internet, also set HSTS_HEADER once TLS is in front of it, and do not skip the auth configuration because it looked complicated during setup.
The wider question — what actually leaves the machine on a self-hosted install, and which stages call out to a model provider — is on the self-hosted privacy page.
8. Publishing to social networks does nothing
The publishing buttons depend on an Upload-Post key, which is a separate integration from the clip pipeline. Without it the buttons are inert — nothing fails visibly, which is why it reads as a bug. Add the key, then republish an existing clip rather than re-rendering it. Autopilot, which clips new uploads on a schedule, is not in the self-hosted stack at all; that is a cloud feature, not a broken key.
9. Someone else's tutorial does not match your screen
Before debugging anything else, check which repo you cloned — this site documents mutonby/openshorts only, and the home page lists the other repositories that carry the same name and how they differ.
If it still fails
Rebuild rather than restart when env values changed (docker compose up -d --force-recreate) — a container keeps the environment it started with. If a stage fails only on longer videos, it is almost always memory; watch the backend container's usage while it runs.
And if you are several evenings into this and starting to wonder whether the setup was worth it, that is a reasonable question rather than a failure: the alternatives page prices each entry tier against what self-hosting really costs, and the self-hosted vs cloud page covers the hosted option that keeps the same output without the maintenance.