Download recovery

Recover failed downloads and replace existing media

Applies to 2026.10.19, which adds clearer failure guidance and preserves existing playable media during replacement downloads.

Find the actual failure

1. Open the source's failed media or Home > Failed.
2. Read the plain-language explanation and suggested action. Follow its Settings or Diagnostics link when provided.
3. Expand Technical details for the original error if the explanation is insufficient.
4. Check whether the item is queued, running, scheduled for another attempt, or has no queued job.

An unknown queue state means the app has not received enough job information to identify the state. It does not establish that the job is absent. Refresh or inspect Diagnostics before submitting another retry.

Fix the cause, then retry

Situation	What to check before retrying
Authentication, age restriction or members-only media	Cookie file, source Cookie Behaviour and availability policies in download settings.
Rate limit or bot challenge	Wait, reduce Download Workers, and check extractor/PO-token configuration where applicable.
Storage, permissions or transfer failure	Free space and write access on both staging and final media storage; container paths and mounts.
Paused/disabled source or prevented item	The source's monitoring/download choices and the item's prevention reason. A retry does not silently change all policy settings.
Removed/private/unavailable video	Confirm availability at the provider; retrying cannot restore a deleted video or grant access.

Use Retry Now for a transient failure. Force Retry can attempt a permanent failure after you review its confirmation. Failed views can filter All, Transient or Permanent failures. A retry replaces work transactionally; an enqueue failure preserves the previous task and is reported rather than counted as success.

Check the resulting queue state and, after completion, the media detail page and file playback. A queued response means work was accepted, not that the file is already downloaded. If a video's publication date falls before its source cutoff, review the dated warning and protect it before downloading when you want to keep it.

Replace a downloaded file safely

Forced replacements and automatic quality upgrades stage the new artifact while keeping the existing media file available. The old copy is replaced only after the new artifact is completed and transferred into place. Pausing or stopping a source also cancels its replacement downloads.

With DOWNLOAD_STAGING_PATH set, the configured staging directory is used. Without it, replacement downloads use .pinchflat-replacements under the media root. Initial downloads retain their normal direct-to-library behavior when staging is unset.

Allow enough space for the old and new copies at the same time. A failed or interrupted replacement preserves the old copy; correct the failure before retrying. Startup cleanup removes eligible inactive staging attempts using the existing one-day threshold and active-item protection. Do not delete staging directories belonging to active jobs.

See Environment variables for staging configuration and retention for quality-upgrade eligibility. Staging does not replace a backup or prevent later automatic cleanup.

Report an unresolved failure

Include the application/image version, yt-dlp version, the action you took, queue state and relevant technical error. Remove credentials, cookies, tokens and private paths. See Diagnostics.

All feature guides