Troubleshooting

Troubleshooting

The most common problems with Studio come down to one of a peer service being unreachable, a credential not being connected, or a run getting stuck. This page covers each, with the symptom first.

My build failed instead of finishing

Symptom: A build stops at failed with an error message naming a service — voiceover, image generation, or script.

Cause: This is Studio working correctly. If a service the pipeline depends on is configured and then fails, the build fails and records the real upstream error. It does not substitute a placeholder and carry on, because a finished-looking video with a silent track or blank images is worse than an honest failure — you’d only discover it after publishing.

Fix: Read the error on the failed build; it names the step and the upstream problem. In local development, start the relevant make dev-* targets (Text-to-Speech, Image generation, Chat) alongside make dev-studio-worker. Then retry — retrying re-queues the same build rather than starting over.

What reaching approval means

A build that reaches awaiting_approval really did run every step. The one narrow exception is a single scene whose voice synthesis failed: that scene is marked distinctly as silent, so the build feed never claims a voice that isn’t there. Fix it by regenerating that scene’s narration.

One scene is silent while the rest have narration

Symptom: The video plays, but a single scene has no voice. The build feed flags that scene rather than reporting it as narrated.

Cause: That scene’s voice synthesis failed — usually the Text-to-Speech service being cold or briefly unreachable. Studio degrades that one scene rather than throwing away the whole build, and marks it so the feed stays truthful.

Fix: Regenerate the narration for that scene from its scene card, or re-voice the whole video. If it keeps happening, the Text-to-Speech service is the thing to check.

A build is stuck and never reaches approval

Symptom: The editor polls forever and never advances to awaiting_approval.

Likely causes and fixes:

• Nothing is draining the queue. The API enqueues work, but a worker executes it. Studio shows a worker banner when the queue isn’t being drained — if you see it, that’s your answer. In local development, confirm make dev-studio-worker is running; without it, builds stay queued.
• The queue is down. Check GET /readyz — if the queue check reports an error, the worker can’t pick up jobs. Confirm Redis (the job queue) is up via make dev-db.
• A step is genuinely hung on a slow service. Studio’s background janitor reaps builds that have been running too long and marks them failed, at which point the Retry button takes over. If a build sits in running for an extended period, give the janitor time, then retry.

A finished video didn’t appear in Drive

Symptom: You approved a run, but the video isn’t in your workspace Drive library.

Cause: Drive registration runs only on a confirmed approve and is best-effort — if Drive isn’t configured for the environment, approve still succeeds but nothing is registered.

Fix: Drive registration requires both DRIVE_API_URL and SUITE_TOOL_SECRET to be set on the Studio service. When either is missing, registration is silently skipped (this is intentional so Studio still works in environments without Drive). With both set, finished videos land in the Studio generated folder as an output-<id>.mp4 file plus its thumbnail — the language isn’t in the filename, so use the Drive file’s details (or Studio’s own project list) to tell variants apart.

My private GitHub repo returns an error

Symptom: POST /v1/source/github returns 404 for a repo you know exists, or 502.

Causes and fixes:

• 404 on a private repo: Studio can’t see it because no GitHub credential was found for your workspace. Connect GitHub once in Connect for the workspace. Public repos need no connection.
• 502 (github_unavailable): Either GitHub rate-limited the request or the credential lookup against Connect failed. Wait out a rate limit, and confirm Connect is reachable and the workspace’s GitHub connection is active.
• 400 (bad_repo_url): The repo URL couldn’t be parsed. Use the canonical https://github.com/owner/repo form.

No global GitHub token

Studio never reads a server-side GitHub token. The credential always comes from Connect, scoped to the workspace in the request. If private-repo reads fail, the fix is always in Connect, not in Studio’s environment.

Publishing to a channel failed

Symptom: A publish moves to failed, or the post never appears on the platform.

Cause: Publishing fetches each channel’s credential from Connect at dispatch time. If the channel isn’t connected for the workspace, there’s no credential to use — and Studio fails the publish loudly rather than reporting a success that didn’t happen.

Fix: Connect the target social account in Connect for the workspace, then publish again. The video must be approved and have at least one render before it can be published. Failures that happen before anything reaches the platform retry automatically up to four times (roughly 2, 10, then 30 minutes apart); a failure reported by the platform is terminal, so a retry can never post twice.

The post is there but looks wrong

Check the destination’s own rules before assuming a bug. Each one honors a different set of visibilities — YouTube all three, TikTok and LinkedIn public or private, Instagram/Facebook/Threads public only — and Studio refuses a combination a destination can’t honor instead of quietly posting at a different one. The publish’s own state and error are shown in Studio, so start there rather than guessing from the platform.

The web app bounces me to login or shows nothing

Symptom: Opening Studio redirects you to sign in even though you’re signed in elsewhere, or the project list is empty after a workspace switch.

Causes and fixes:

• CORS / redirect rejection: The Studio API only accepts the web origins in its allowlist. Confirm STUDIO_CORS_ALLOWED_ORIGINS and STUDIO_WEB_URL_ALLOWLIST include the origin you’re loading the app from.
• Wrong workspace: Studio is workspace-scoped — projects belong to one workspace. If you switched workspaces and the list looks empty, you’re seeing the new workspace’s (empty) library, not a bug. Switch back, or create a project in the current workspace.

Controller callback routes return 404

Symptom: The worker’s callbacks to the API (or your own probes of /v1/controller/*) return 404.

Cause: Controller routes are gated by IDENTITY_CONTROLLER_SECRET. When that secret is unset, the routes are intentionally invisible.

Fix: Set the same IDENTITY_CONTROLLER_SECRET on both the API and the worker so they agree. With it unset, the worker can’t report progress and runs won’t advance.

Database-backed routes fail right after boot

Symptom: /healthz is fine, but project and run endpoints fail.

Cause: STUDIO_DATABASE_URL is unset, or migrations haven’t been applied. Studio boots its sign-on shell without a database so health checks pass, but every data route needs the database.

Fix: Set STUDIO_DATABASE_URL and apply migrations:

cd apps/studio/api && go run ./cmd/migrate up

Then confirm GET /readyz reports the db check as healthy.