Troubleshooting

Start with the shortest failing operation and the Logging page. Increase log level only long enough to reproduce the problem, then restore normal verbosity.

Web UI does not open

1. Run upbrr serve --help and verify the intended host and port.
2. Check startup output for listen errors.
3. Open http://localhost:7480 manually for the default configuration.
4. If using Docker, confirm the container is healthy and port 7480 is published.
5. If another process owns the port, select another with --port.

The default host is localhost, so another machine cannot connect unless you deliberately bind a network address or use Docker's 0.0.0.0 default.

First-run setup is exposed

Stop the instance or restrict its port to loopback until setup is complete. First-run account creation is reachable by anyone who can reach an unconfigured instance.

A release folder is missing from the browser

• Confirm the path is inside a configured browse root.
• Confirm the upbrr process can read the folder.
• In Docker, mount the folder and select its container path, such as /data/....
• Remember that config import does not import browse roots.

Do not enable unrestricted browsing solely to hide a mount or permission error.

A reverse-proxied page partly works

If HTML loads but assets, login, API calls, or live progress fail under /upbrr/:

1. set --base-url /upbrr/ or UPBRR_WEB_BASE_URL=/upbrr/;
2. keep /upbrr/ on both sides of proxy_pass;
3. inspect browser requests for /upbrr/api/... and /upbrr/assets/...;
4. disable proxy buffering for live event streams;
5. configure trusted proxies when HTTPS terminates upstream.

See the reverse proxy guide.

An operation was interrupted by restart

Startup retains completed operation checkpoints and marks unfinished operations interrupted. It can wait for prior-process input and work leases to expire before cleanup. It does not automatically repeat the interrupted command. Input starts empty, even when the prior workflow retained HDR analysis or was waiting for feedback. Explicitly reopen the source from History or Input before continuing. Startup does not require the old source to be available; the explicit open checks availability.

For an interrupted upload or client injection, check the tracker and torrent client before retrying. Startup retains unresolved external attempts as uncertain and keeps their retry blocks; an interrupted operation is not proof that the remote action failed. Confirmed successful tracker submissions remain recorded and must not be submitted again.

A tracker response that explicitly rejects an upload is a failed submission, rather than an unknown outcome. Correct the reported problem before preparing and reviewing a new attempt. An accepted upload remains accepted if retrieving its torrent or injecting it into the client fails. If the local submission receipt could not be saved, the result reports that bookkeeping failure separately and keeps retries blocked. Do not confirm that an accepted submission did not complete to bypass this block.

During legacy recovery, retained proof for the exact accepted attempt settles that effect so it no longer keeps the shared input slot occupied. Other uncertain attempts still require reconciliation, and the accepted upload's retry blocks remain in place.

An upload blocked by an older uncertain attempt offers confirmation only when the exact receipt belongs to the current workflow. A fence owned by another workflow remains protected and cannot be confirmed from the new workflow.

An unresolved tracker submission does not prevent independent CLI queue items from running when its durable submission protection remains available. Legacy attempts without that protection still require reconciliation before new inputs. The affected source remains protected until reconciliation; resuming the queue selects its other pending items. Missing or contradictory retained source information still requires manual recovery.

If configuration also changed while an external outcome is uncertain, startup keeps the existing activation blocked rather than clearing the outcome. Resolve the uncertainty before activating the changed configuration.

If Legacy workflow recovery still appears, inspect each listed remote outcome. Choose Confirmed not completed; allow a fresh exact attempt only after confirming it did not complete. Do not delete History simply to bypass an uncertain outcome: deletion also removes local repeat-submission protection.

FFmpeg is not found

Run ffmpeg -version in the same environment that starts upbrr. On Windows, add FFmpeg's directory to PATH before starting upbrr or its service. Containers already include FFmpeg.

The Web UI Application Details surface reports detected FFmpeg capability without exposing the local executable path.

Audio analysis fails or is incomplete

Audio analysis depends on the exact audio streams found during release preparation. If no tracks are available, return to Input and verify the source and prepared technical data. If an explicit ordinal is rejected, remember that --audio-tracks uses one-based audio-only ordinals rather than container-wide stream indexes.

For a failed track or image:

1. verify that the same FFmpeg installation can inspect the source;
2. check whether the source changed after preparation;
3. review the bounded failure message shown for that track and variant;
4. retry the analysis to regenerate only compatible missing or failed images;
5. re-prepare Input when the source or stream mapping changed.

Sources with more than eight channels per selected track are unsupported. Malformed or truncated decoded sample data is rejected rather than rendered. Cancellation can leave a partial result; successful PNGs remain visible while failed or missing variants can be retried.

FFmpeg streams decoded float PCM directly to upbrr; no full decoded-audio file is saved. Selected tracks needing the same image types normally share one pass over the source at their native sample rate and channel layout, without normalization, resampling, or downmixing. Missing or inaccurate duration metadata can require another decode for exact spectrogram timing. If the audio changes between passes, upbrr rejects the result; re-prepare Input before trying again.

HDR analysis is partial or inconclusive

Review the native-format outcomes separately from picture checks and audio tracks. A successful HDR10+ plot does not establish Dolby Vision availability, and completed native metadata does not prove that a picture check ran. Require both formats needs both; use automatic discovery when you want whichever native formats are present.

• Unsupported picture check: verify FFmpeg availability and the reported colour, geometry, or timing requirement. Native metadata can still be usable; select metadata-only mode if that is the evidence you need.
• Inconclusive scene or border check: inspect confidence, measured candidates, missing coverage, and the reported reason. Bounded and sampled checks can miss short events; an inconclusive result is not a pass or proof that the media is defective.
• Grayscale scene thumbnails: colour previews can fall back to grayscale when unavailable. Detection uses luminance independently; consult the numeric result. SDR preview colours are not HDR brightness measurements.
• Audio stopped near the end: decoding, rendering, and artifact publication are separate phases. Read the terminal result instead of treating a progress percentage as completion. A failure after decoding can leave usable retained measurements or images.
• Partial attempt: preview successful artifacts and retry compatible rendering. A new measurement pass must explicitly select unsuccessful modes from the current attempt. Do not use old artifact or attempt IDs after preparing a different generation.
• Source changed or retained metadata is missing: prepare Input again or follow the reported recovery requirement. Retrying decoded work does not grant a new native scan.

If descriptions omit expected images, verify the selections on HDR Analysis. Native plots and selected audio are default assets, but picture-check images require selection. HDR-produced audio belongs under Audio Plots; video evidence belongs under HDR plots. Saved final description edits remain authoritative: inspect or reset the edited group when you want a regenerated version.

See HDR analysis for mode selection, borders, reference alignment, and retention.

A Blu-ray scan appears stalled

Enable debug logging to see BDInfo progress for full-disc and selected-playlist scans. In the CLI, use --log-level debug; in the Web UI, set the runtime level on Logging. The --debug upload option controls workflow behavior and is separate from log verbosity.

BDInfo logs each crossed 5% threshold through 95%, with the scan stage, source path, and selected playlist (empty for a full-disc scan). Percentages restart for each stage and scan; stream scanning uses processed bytes, while other measured stages use completed item counts. These are stage percentages, not an estimate of total elapsed time. A jump can produce several threshold entries at once, but repeated callbacks within the same interval do not repeat them. The final stage=done percent=100% entry appears only after processing and report persistence succeed. Failed or canceled scans, including reports with recorded scanner errors, do not emit it. Progress logging also works when no CLI or Web UI progress display is attached.

A multi-disc source is rejected

Multi-disc support accepts extracted, homogeneous DVD or BDMV directory collections. Select the collection parent and use one marker type under every disc folder:

• Disc 1/VIDEO_TS and Disc 2/VIDEO_TS; or
• Disc 1/BDMV and Disc 2/BDMV.

Mixed DVD/BDMV collections are rejected. Nested or multi-disc HD DVD collections are unsupported; only an existing single direct or immediate HVDVD_TS layout remains compatible. ISO images and optical drives are not discovered as multi-disc inputs, so extract or copy each disc into a directory layout first. Directory symlinks are also rejected.

Automatic DVD menu capture fails

Automatic capture accepts an extracted DVD directory containing VIDEO_TS, VIDEO_TS itself, or a supported multi-disc DVD collection parent. Multi-disc results are grouped by disc; a partial-coverage warning means the collection-wide capture cap or available menus left at least one disc uncovered. Automatic capture does not accept ISO images, optical drives, or Blu-ray menus.

The selected FFmpeg must expose the dvdvideo demuxer plus menu, menu_lu, menu_vts, pgc, and pg. Encrypted, protected, unreadable, region-restricted, or corrupt inputs can still fail. upbrr does not provide CSS decryption.

Use manual disc-menu image import when automatic capture is not available.

A metadata provider fails or selects the wrong title

Updates that change external-ID interpretation rebuild older automatic identity data when the input is prepared again. Explicit ID selections and cleared providers remain authoritative; compatible cached descriptions and images are retained.

Supply the correct provider ID, or clear the provider when you want to continue without it. For example, --tmdb= or --tmdb=0 clears TMDB in the CLI. See clearing a metadata provider for all supported flags and examples.

In the Web UI, use the metadata ID controls on Input, then click Refresh metadata. If the first fetch fails before a preview appears, remove the provider and click Retry metadata instead.

Clearing prevents that provider's ID and metadata from being rediscovered for this source. It persists across release reloads. Supply a positive ID to use the provider again.

Check tracker eligibility after the change. A tracker that requires the missing provider can remain blocked, while other eligible trackers can continue.

Tracker authentication is blocked

1. Open Settings → Trackers, confirm every required field is present, and save changes.
2. For cookie-file authentication, follow the Firefox export and import walkthrough, or use the tracker's supported login flow.
3. Complete 2FA when requested.
4. Open Settings → Tracker Auth, inspect the stored cookie status/count, and select Check Auth where supported.
5. Retry preparation after resolving the reported auth requirement.

Stored cookies do not prove a valid remote session. See Cookie troubleshooting for wrong Firefox containers, expired sessions, rejected formats, missing folder imports, and tracker-side failures. For Storage unavailable, follow Storage recovery; do not delete the database or auth key material.

Upload preflight can validate sessions and perform tracker-supported automatic login or refresh, including storing a refreshed session. If authentication remains blocked or requires manual 2FA, resolve it under Settings → Tracker Auth before retrying preparation.

No screenshots or image links

• Confirm FFmpeg access and screenshot count.
• For imported screenshots, enable Settings → Metadata → Collect existing tracker images, inspect Tracker Data, and open Screenshots to review the automatically included images. Unselect or delete unwanted images in the normal screenshot list. Only usable validated images are eligible; an imported comparison block alone does not supply ordinary screenshots.
• Confirm the chosen image host is configured and allowed by the tracker. Images tied to their source tracker may need downloading and rehosting, even when they display correctly in the original description.
• If a saved screenshot’s local file is missing or changed, its retained hosted URL remains listed under Upload Images, where you can remove the saved association. It is not a local upload candidate.
• Review host-specific failure messages without copying credentials or raw responses.
• Check min_successful_image_uploads: zero requires the whole batch to succeed; a positive value permits a partially successful batch only after that many images publish.
• Use --skip-imagehost-upload only when you will supply valid hosted images another way.

Config import reports warnings

Warnings can identify unknown legacy keys, unsupported tracker fields, or unsupported image-host settings. Open Settings and correct each affected group. An import warning is not proof that the remaining configuration is ready for live upload.

Unattended mode stops

--unattended never prompts. It stops when a workflow-global decision or unsafe ambiguity needs operator input. Use --unattended_confirm only when prompts are acceptable, or provide the missing input explicitly.

A tracker-specific manual prerequisite can block that tracker while other viable tracker lanes continue.

Safe issue reports

Include:

• upbrr version and operating system;
• binary or Docker installation;
• the shortest reproduction using Example.Release.2026.1080p-GRP;
• sanitized logs around the failure;
• expected and actual stage outcome.

Exclude config exports, API keys, passwords, cookies, passkeys, announce URLs, OTP data, private tracker pages, and raw request or response bodies.