Symptom first. Each entry names the likely cause and the page that explains it properly.

Before working through a symptom, look at Settings → System → Status: the readiness card names most misconfigurations directly, and rdownloader doctor names the rest.

Symptom	Cause and fix
The native Linux binary fails with GLIBC_2.39 not found	The system's glibc is older than 2.39 (Debian 12, Raspberry Pi OS bookworm). Run the container image there, which carries its own. The minimums of every platform are on the support matrix.
rd-api fails to build from source	The web frontend was not built first. It is embedded at compile time.
The Windows launcher says the capture agent is not paired	Not a failure. Pair it under Settings → Clients & API → Desktop, or ignore it if you do not use the agent.
The Windows launcher says port 9666 is busy	Not a failure. A second capture agent from autostart, or JDownloader, has the Click'n'Load port. Decide which should keep it.
The launcher window closes before you can read the error	It stays open only for a real failure. RDOWNLOADER_NO_PAUSE=1 suppresses that pause.
The container never becomes healthy	The first start takes about a minute for plugin installation. Wait for rDownloader listening in docker logs.
The service stops at start: the stored setting … cannot be used	A value the queue runs with does not read. Stop the service and run the json_remove statement the message quotes; the field then reads as its default. See Diagnostics and maintenance.
The service stops at start: another rDownloader service already runs on …	One service per data directory. rdownloader stop, or rdownloader doctor to see which one runs.
A wrong UI port locked me out	It cannot. --listen and RDOWNLOADER_LISTEN always override the ui_port setting.
A settings page is not where you expected it	The settings are grouped into six rubrics, each page with an address of its own; the overview at Settings lists all of them. See Defaults and limits.

Symptom	Cause and fix
Windows shows Windows protected your PC for the installer	The installer is not code-signed yet. Check it against SHA256SUMS on the release page, then More info → Run anyway. See Installation.
start-rdownloader is not found after winget install	The terminal was open before the install and does not see the changed PATH. Open a new one.
The deb or rpm package is installed, but nothing answers at port 8710	The package starts nothing by itself. systemctl --user daemon-reload && systemctl --user enable --now rdownloader.
After moving the data folder to another machine or user account, accounts, Usenet servers, indexers or notification targets fail with secret.unreadable	The stored credentials are encrypted with a master key kept in the old system's credential store, which did not move with the folder. Enter those credentials again, or restore a full backup with its passphrase, which carries them. The start logs a warning and rdownloader doctor counts how many cannot be read.
An installed build does not see the data of the portable copy	An installed build keeps its data in your user's data folder, not beside the program. Move data/ and downloads/ there — see where the data lives.
An update is refused with update.backup_failed	The backup before the update could not be written and checked; the message names the step and the cause, usually free space or the backup passphrase. Nothing changed. See Updates.
After Install and restart the old version runs again	The new version did not start properly, so rDownloader went back to the previous one with the database from before the update. The dialog names why; report it with a diagnostic bundle.
An update through the Windows installer ends with update.msi_rollback_unavailable	The first update after installing by hand has no previous installer to go back to, so the new version stays. Install the previous version from its release page if you need it. See Updates.
On macOS, after brew upgrade, the service does not answer and its log says keychain_interaction_refused	The keychain item with the secret store's key trusts only the build that created it, and a background service cannot ask you. Start the service once in a terminal and choose Always Allow, or allow the new program for the item rDownloader in Keychain Access; then start it again. Nothing in the secret store is changed meanwhile. See Installation.
Every other update.… code	See the table on Updates.

Symptom	Cause and fix
Everything sits in Queued	Check the global Start all / Pause all state, and the active-files limit (default 3).
Entries are Blocked with a service reason	That transfer service is switched off under Settings → Services; the service's own settings page says so at its top and leads to the switch. Switching it back on returns them to the queue.
A storage root is refused with storage_root.protected_directory	The path is, contains or lies inside rDownloader's data, scripts, vendor, tool or plugin folder. Choose a folder of its own. See Storage, categories and rules.
Entries are Blocked with storage.capacity_blocked	The storage root is below its free-space threshold. Free space, then release it — the block is persisted and survives a restart. See Storage, categories and rules.
Downloads never start after a certain hour	A bandwidth profile or an exhausted traffic budget. The status names which limit applies.
The queue is held with a battery or metered reason	Power settings are holding it deliberately.

Symptom	Cause and fix
A free download waits a long time	One free download at a time per hoster, by design — a second would break the first one's session. See Hosters and accounts.
Every free link of one hoster is held back	An IP block. It clears when the hoster says so, or after 15 minutes when it names no duration. Premium downloads are unaffected.
A widget captcha shows a hint instead of a picture	reCAPTCHA, hCaptcha and Turnstile are bound to the hoster's domain and are never rendered inside rDownloader. Either a configured solver answers it, or you answer it yourself through the browser extension, which opens the hoster's own page.
A widget captcha is waiting and the extension never offers it	The extension polls every 30 seconds and only once paired. Check the pairing in its options, and that the prompt reports an extension as connected.
An account test ends with "showed no captcha in your browser"	The browser is most likely signed in at that hoster already, so the login page skipped its form and there was no captcha to answer. Take the session over with Take over from browser at the account, or sign out of the hoster in the browser and test again. See Hosters and accounts.
Saving a cookie profile or account cookies is refused	A cookie is set for a public suffix such as com, or for a domain outside the profile's host. Nothing was stored; export the cookies for the site itself. See Where a cookie may go.
The solver refuses	Test the key under Settings → Captcha & solver — it reports the balance or a translated reason. A rejected key or empty balance stops the attempt rather than quietly asking you.
A captcha vanished after a restart	Waiting captchas are held in memory only. The download returns to the queue and raises a fresh challenge.
A link is refused with plugin.address_carries_marker — the address contains a credential placeholder	The address contains {{, as written or percent-encoded, which a plugin could have filled with an account's credential; a link check shows it as unknown. A genuine link does not carry one — check where it came from. See A credential placeholder counts only where the plugin wrote it.
The finished file is a hoster's landing page	It is not — a plugin-resolved link answering with markup fails with download.not_a_file, quoting the hoster's wording.
An account's provider disappeared	Its plugin was uninstalled. The account stays editable so you can switch it off; a provider exists exactly while its plugin does.

Symptom	Cause and fix
Only progressive formats are offered	ffmpeg and ffprobe are not both available. Without them nothing can be merged. See External tools.
A video fails with "yt-dlp could not reach ffmpeg" (media.merge_ffmpeg_unreachable)	yt-dlp downloaded video and audio as separate files and could not merge them, so the download does not count as completed. Check the ffmpeg path under Settings → Tools → Paths and what was found under Settings → Tools → Status, then retry.
A capability is blocked with media.tool_incompatible	The tool is below the tested floor or on the known-bad list. The error names the tool, version, minimum and capability.
A tool version reads as unknown	It could not be parsed — an FFmpeg git build, for instance. That never blocks anything.
A media link is refused when queued: "no format selected that can be downloaded"	The page offered nothing to choose from — no downloadable format, or video without a single audio track. Check the link again or remove it. A page that merely names no codecs is not this case; it offers Best.
A YouTube playlist stays one link "playlist" with check failed	Versions before 1.24 opened every video of the playlist first, which took too long or failed on one private video. Update; a playlist then expands into one link per video, up to 200. See Video and audio downloads.
A format selection matches nothing	The selector shows how many formats each criterion would keep on its own, which tells you which one is the problem.
A stream is refused as DRM-protected	It is. Ordinary AES-128 encryption is not DRM and works.
A subtitle or chat sidecar is missing	Recorded with the reason. Subtitles and live chat are unsupported for recordings: streamlink passes the muxed stream through.
A private page downloads the public version	It should not — a pinned cookie profile that is disabled, expired or scoped elsewhere fails the download instead. Check the profile.

Symptom	Cause and fix
NZB downloads do not start	No NNTP server is configured, or none is enabled. Settings → Usenet, then Test.
An NZB is refused	Over the 64 MiB limit, or already in the history as a duplicate. Delete the history entry to import it again.
PAR2 repair says the set is unusable	The main index and every .vol file failed to parse: the recovery set is genuinely damaged.
Unpacking fails with extract.tool_outdated	The unrar in use is older than 6.12, or the 7-Zip older than 25.00: both let an archive write outside the destination, so neither is started. Point External RAR tool under Settings → Tools → Paths at a current unrar, drop a current 7-Zip into the vendor folder, or remove the old binary from PATH. See External tools.
Unpacking fails with extract.tool_too_old	The unrar in use is older than 6.10 and does not know the switch the destination is passed in. Replace it as above.
Unpacking fails with archive created a hard link	A file the archive tool wrote has a second name, a hard link to a file outside the extraction folder. The unpack is refused before anything reaches the package folder; the archive is not safe to unpack.
A password with a " is skipped on Windows (extract.password_has_quote)	7-Zip cannot receive a quotation mark in a password on Windows, so that candidate is not tried and the next one is. Unpack such an archive by hand.
PAR2 repair treats a set as unreadable although its files look fine	The set names a file outside its own package (an absolute path or ../). It is ignored on purpose and repairs nothing.
A package is stuck after a failed verification	"Post-process only verified packages" is on. Use Post-process anyway on the package to run the pipeline once without changing the setting.

Symptom	Cause and fix
Nothing is uploading	Data sharing is off by default, at the engine. Switch it on deliberately under Settings → BitTorrent.
An option is disabled in the interface	The embedded engine does not support it. GET /api/v1/torrents/capabilities says what it can do.
Files in one priority tier download together	File priorities are emulated by opening one tier at a time; within a tier they are concurrent.
A web seed is listed but never used	BEP 19 web seeds are parsed and displayed but never fetched.
All torrents paused themselves	The kill switch — the bound network interface disappeared. They resume when it returns. Downloads shows a warning while it holds them; Settings → BitTorrent → Network status says which interface is missing.
Saving the BitTorrent settings says Another program holds port …	Another program — often another torrent client — listens on that port, and the engine does not share it. Choose another Listen port, or close that program and save again.

Symptom	Cause and fix
An SFTP server is blocked with a fingerprint	Unknown host key. Compare the SHA256: fingerprint and confirm it once.
An SFTP server is blocked with two fingerprints	The key changed. This is never accepted automatically — a rebuilt server and an interception look identical from here.
A resume is refused and the partial file kept	Size or modification time moved. That is the safe outcome; restart the transfer.
An FTP transfer says a restart is needed	The server refuses REST, or a WebDAV server has no Accept-Ranges.

Symptom	Cause and fix
403 with request.host_not_allowed — "This service does not answer to the name …"	You opened rDownloader by a host name that is not the external URL's host. Open it by its IP address or localhost, then add the name under Settings → Security → Reachability & reverse proxy → Allowed host names. See Reverse proxy.
Through a Cloudflare Tunnel the browser shows rDownloader does not answer to this host name	The tunnel's public name is not allowed yet. Open rDownloader at http://127.0.0.1:8710 on its own machine (or by its LAN address), set the tunnel's address as the external URL and 127.0.0.1 as trusted proxy. See Cloudflare Tunnel.
The login is switched off, but the password is still asked for	Disable admin login applies to this computer only. Another machine, a reverse proxy and a Docker port mapping always sign in.
Signing in works, then the login screen returns	The session cookie is Secure on a plain-HTTP deployment, so the browser drops it. Set cookie_security. See Reverse proxy.
Everyone shares one rate limit; one address for every session	No trusted proxy configured, so the proxy's address is treated as the client's.
The page loads blank under a sub-path	The mount point is not configured. Set external_url including the path.
Passkeys are refused	Without external_url, passkeys work only at http://localhost:<port> — not at 127.0.0.1, because a relying party id must be a domain.
Passkeys stopped working after a move	Changing external_url invalidates them. The password still signs in; enrol them again.
I lost my authenticator	Use a recovery code, or switch the second factor off with your password.
I want to change the administrator password	Settings → Security → Sign-in → Administrator password, with the current one. Every other session ends; API tokens keep working, so review them.
I forgot the administrator password	Run rdownloader auth reset-password on the computer rDownloader runs on (Docker: docker exec rdownloader rdownloader auth reset-password). It prints a new password once and ends every session; replace it afterwards under Settings → Security. See Accounts, sessions and permissions.
Pairing the capture agent over the network is refused	A non-loopback address must be https, or pairing needs --allow-insecure-service. The token rides on every poll, so it must not travel in the clear.
An MCP client's token is always refused	Two Authorization header sources — only the first is read. Configure exactly one.
An API call answers auth.scope_insufficient	The token lacks that permission area. Add the missing area to the token in the token list (areas can be changed after issue), or issue one with it.
A capture token does not work on the API	By design. Capture and API tokens are strictly separated.
A file the extension hands over is refused with capture.fetch_address_refused	Its address, or an address a redirect leads to, is on this machine. rDownloader never fetches those for the extension; addresses in your own network work.

Symptom	Cause and fix
Permission errors on every write	PUID/PGID do not match the folder owner on the host.
The container exits with PUID=… is not a numeric id or would run the service as root	Set PUID/PGID to the numbers id -u/id -g print. Root runs only with RDOWNLOADER_ALLOW_ROOT=1. See Docker and NAS.
A storage root is badged NOT PERSISTENT	The path is not mounted. Add a volume before downloading anything you want to keep.
Sonarr, Radarr or the browser get 403 by a name with a dot	A name without a dot (rdownloader, nas) and names under .local, .home.arpa and .internal are always accepted; a name such as nas.lan or rdownloader.example.org is not. Add it under Settings → Security → Reachability & reverse proxy → Allowed host names.
The login is switched off, yet every request asks for it	Behind a port mapping no request comes from the container's own loopback address, so the login always applies in Docker.
Schedules fire at the wrong time	TZ is unset, so the container runs on UTC.
No hoster resolvers	The startup log says no bundled plugin packages found.
The container stayed stopped after Restart now	rDownloader ended with exit code 75 for its restart, and the container has no restart policy. docker start rdownloader, and add restart: unless-stopped (compose) or --restart unless-stopped. See Docker and NAS.

Symptom	Cause and fix
A plugin is listed as incompatible	Built for an older contract, or asking for a permission this version does not know. The reason is shown rather than the plugin being ignored.
A disabled plugin is still listed	Deliberate — so it can be switched back on. It takes effect on the next start.
Two versions of one plugin are installed	Installing never removes the older one. The Versions panel on the plugin's card shows which one runs and which one the next start runs.
A version choice or an update has not taken effect	Every version choice and every installed update applies at the next start; the card says Restart to apply. Use Restart now (sidebar: Restart pending), or switch on Restart automatically when needed — see Restarting when needed.
An update installs only on a click although updates are automatic	It is marked New permissions: it asks for more than the installed version, so it waits for your review.
A download says its plugin version "has been withdrawn" (plugin.pinned_version_withdrawn)	The version it was pinned to was withdrawn. Resume it to continue with the plugin's current version.
A repository install fails with "does not match its index entry"	The downloaded package differs from what the repository's index says about it — publisher, permissions, version or digest. Nothing was installed; tell the repository's publisher.
A repository shows "Last check failed"	The index could not be fetched or did not verify — expired, older than one already accepted, or signed by another key. The last good index stays in use while it still verifies.

Symptom	Cause and fix
The log viewer says records were dropped	The store could not keep up; logging drops records rather than hold up a download. Lower the log level if it keeps happening.
A log line you expected is missing	The store sees exactly what stderr sees, and trace is never stored. Raise the log level, or use Debug for a while for one area, and reproduce. A plugin's lines beyond 50 in one call are summed up in one warning.
Creating a diagnostic bundle is refused as stale	The inventory changed between the preview and the approval. Draw the preview again and approve that one.
A bundle cannot be written	No data directory is configured; there is nowhere to put it.
An entry disappeared from the audit log	Only retention removes records, oldest first and whole. Nothing else deletes one.
Clean up now says the database was not rewritten (system.cleanup_rewrite_busy)	A database from before 1.24 is rewritten once to hand its free space back, and never while anything downloads, verifies, unpacks or records. The rest of the clean-up ran; try again once everything is done. See Cleaning up the data folder.
The rewrite is refused with system.cleanup_rewrite_no_space	The data folder needs room for a second copy of the database. Free space on that drive, then clean up again.
Old skipped or dismissed entries are gone from a subscription's archive	After 30 days (Keep skipped subscription entries whole) they keep only what the subscription recognises them by, so they do not come back. 0 keeps them whole. See Subscriptions.

1. rdownloader doctor — see Diagnostics and maintenance.
2. Read the log viewer, filtered to the correlation id of the work that failed, or raise the log level — for one area, Debug for a while.
3. Check Defaults and limits — the behaviour may be a documented default.
4. Read the FAQ.
5. Create a diagnostic bundle before asking someone else to look.

• Diagnostics and maintenance
• Defaults and limits
• Support matrix — what runs where, and how it is tested
• Updates — every update code
• Transfer states
• FAQ