Troubleshooting

Most problems announce themselves. When OpenBBQ stops with an error, the message carries a stable error code and usually a fix — a concrete next step. Follow that fix first.

Start here

When you need a wider look, two commands tell you most of what is wrong:

openbbq doctor
openbbq --json status --workspace workspaces/demo

doctor checks your machine; status shows what happened inside one workspace.

openbbq command not found

Confirm that uv installed the tool and that your shell can see it:

uv tool list
uv tool update-shell

Open a new shell, then try openbbq --help again.

The whisper.cpp recognizer is missing

The recognizer is an optional add-on. Install or repair it, then check:

uv tool install --force 'openbbq[whispercpp]'
openbbq doctor

The model is missing

Models are downloaded separately. See what you already have, then pull one:

openbbq models list
openbbq models pull large-v3-turbo

Or let the recognizer download it on the spot:

openbbq transcribe --model large-v3-turbo --auto-download

If a download stops halfway, pulling again resumes where it left off when the server supports resuming (HTTP ranges). If the finished file is the wrong size, OpenBBQ removes the invalid download and asks you to retry.

GPU or native backend failure

The default is --gpu. Retry on CPU:

openbbq transcribe --model large-v3-turbo --cpu --workspace workspaces/demo

Native backends can also fail inside restricted sandboxes even when they work in a normal terminal. Try a regular user environment first before concluding the backend is broken.

FFmpeg missing or subtitle filters unavailable

openbbq doctor
ffmpeg -hide_banner -filters

Burning subtitles into video needs both the ass and subtitles filters. If they are missing, install an FFmpeg build with libass — see Installation — or point burn at an FFmpeg that has them:

openbbq burn --ffmpeg /path/to/ffmpeg --workspace workspaces/demo

No workspace found

Run the command inside the workspace folder, or pass it explicitly:

openbbq status --workspace /path/to/workspace

A valid workspace contains an OpenBBQ manifest.json — its progress log — not just any file with that name. Workspaces and stages explains the idea.

Fetch asks for login or human verification

Some platforms won't serve a video until you log in or prove you're human. Log in once, then fetch again:

openbbq auth browser-login youtube
openbbq auth status youtube
openbbq fetch --workspace workspaces/demo

If a public video fails only while you're logged in, fetch without the saved login:

openbbq fetch --workspace workspaces/demo --no-auth

If the saved login itself has gone bad, clear it and log in again:

openbbq auth clear youtube
openbbq auth browser-login youtube

Translation is incomplete

openbbq translate check zh --workspace workspaces/demo

It lists the ids of the subtitle lines still missing a translation. Fill them in and check again. --allow-missing on export is only for an intentional draft — untranslated lines fall back to the source text.

The worksheet no longer matches the subtitle lines

This usually happens after rerunning segment, which recuts the lines. Before regenerating the worksheet, keep the old one safe, then match your translations back to the new lines by id and source text. Careful: translate init --force discards the old file immediately.

Burn rejects the input

• An audio-only workspace has no picture to burn into — it can't produce a burned video.
• The subtitle must be an .ass file; re-export with --format ass.
• Without --subtitle, burn uses the most recent export, which may be SRT. Export ASS again or pass the ASS file explicitly.
• Burn also refuses a workspace ASS that changed since export or isn't tracked — re-export, or pass the file explicitly. --allow-stale is only for an intentional hand-edited draft.

openbbq export --to zh --mode bilingual --format ass --workspace workspaces/demo
openbbq burn --workspace workspaces/demo

A running stage goes stale

If a running step sends no heartbeat — no sign of life — for 60 seconds, status marks it stale. Make sure no process is actually still active (check its logs), then rerun the affected command. Rerunning refreshes that stage and invalidates the downstream results that depended on it — Quality gates explains how stages depend on each other.

Still stuck?

The CLI reference lists every command and option, and Workspace files explains what each file in a workspace is for.