Troubleshooting

Common Issues

Docker permission errors

Files created by Comicarr are owned by the wrong user, or media volumes are not writable.

Cause: The PUID and PGID environment variables do not match the owner of your mounted volumes.

Fix: Run id on the host and set the values in your docker-compose.yml:

id
# uid=1000(user) gid=1000(user)

environment:
  - PUID=1000
  - PGID=1000

Recreate the container after changing these values. The entrypoint warns if /comics, /downloads, or /manga are not writable; fix host permissions rather than chown-ing media trees inside the container.

First-run setup token required

Setup fails with “Invalid setup token”.

Cause: On first run, Comicarr generates a one-time setup token and requires it when creating the admin account. It is printed to the server console and container logs, not shown in the browser.

Fix:

docker logs comicarr 2>&1 | grep SETUP

Enter the printed token on the setup form along with username and password (min 8 characters).

ComicVine API rate limiting

Metadata lookups fail or return errors when adding multiple series.

Cause: ComicVine enforces rate limits. The default CVAPI_RATE is 2 requests per second.

Fix:

• Reduce CV_MAX_PARALLEL_REQUESTS (config / ComicVine settings under Settings → API & providers area for related options)
• Enable ComicVine response caching to avoid redundant requests
• Space out bulk additions rather than adding many series at once

Download client connection failures

Comicarr cannot reach SABnzbd, NZBGet, or a torrent client.

Fix:

• For SABnzbd, check the URL, API key, category, download directory, and TLS verification in Settings → Download clients. For NZBGet, blackhole, and torrent clients, verify host, port, and credentials in config.ini
• If both services run in Docker, use the container name as the hostname (e.g., sabnzbd instead of localhost)
• Check that the containers are on the same Docker network
• Test connectivity from inside the Comicarr container:

  docker exec comicarr curl -s http://sabnzbd:8080

Encrypted credentials after config restore

After restoring a config.ini backup, credentials fail to decrypt.

Cause: Encrypted values (prefixed with gAAAAA) are tied to the master key in .secure/master.key. If the key file does not match, decryption fails.

Fix: Copy the entire .secure/ directory, or at least master.key, alongside config.ini when migrating or restoring. If the key is lost, re-enter all credentials; they will be re-encrypted with the new key.

Search returning no results

Automatic or manual searches find nothing for series that should have results.

Fix:

• Open Settings → Acquisition → Route readiness first. It says which of the DDL, NZB, and torrent routes is usable and what each one is missing, which beats reading config
• Confirm API keys are valid for each provider
• Check USENET_RETENTION (default: 3500 days) and reduce it if your provider has shorter retention
• Review provider order settings so preferred providers are enabled
• Raise the level to 2 · Debug in Settings → Logs, run one search, and read the provider lines it produces

A Torznab provider is configured but never searched

You added a Torznab indexer, in Settings → Search → Torrent indexers (v0.33.0+) or in config.ini, and no torrent searches happen, with no error.

Cause: A Torznab provider needs four separate switches on. The legacy single-provider fields do not count toward any of them. The Settings editor covers ENABLE_TORZNAB ("Enable Torznab indexers") and the per-provider enabled flag, but the two [Torrents] master switches still live in config.ini.

Fix: Verify all four, then restart:

[Torrents]
enable_torrents = True
enable_torrent_search = True

[Torznab]
enable_torznab = True
extra_torznabs = Prowlarr, http://prowlarr:9696/1/api, 1, YOUR_API_KEY, 7030, 1

The last field of the entry (1) is that provider's own enabled flag. Also check that the host is the complete Torznab feed URL. Comicarr appends the query string to it verbatim and will not add a missing /api or /torznab suffix.

If you set torznab_name / torznab_host / torznab_apikey / torznab_category by hand: those keys are not read by the search code. Since v0.29.1 Comicarr folds a complete set into extra_torznabs at startup and removes them; an incomplete set is reported in the log and ignored. Look for [CONFIG] lines mentioning torznab. Full detail: Search Providers.

Pack and bundle releases are always rejected

Searches find a multi-issue pack or a volume bundle, which is the usual shape for manga and manhwa torrents, and Comicarr never grabs it.

Fix: Open the series detail page and enable Allow packs under Search options. If results are also being rejected for a book-type mismatch (TPB, GN, and similar), enable Ignore book type as well. Both are per-series and default to off. Pack matching also requires torrent search to be enabled. Since v0.34.0 packs are matched from any indexer, and one grab marks every issue the pack covers as Snatched. Since v0.36.0, a series with Allow packs on also sends a bare-title query to Torznab indexers, which is what turns up pack-shaped titles on trackers like Nyaa; numbered queries never do. See The bare-title pack pass.

Post-processing failures

Downloaded files are not moved or renamed after download completes.

Fix:

• Verify path permissions: the container user (PUID/PGID) must have write access to both /downloads and /comics
• Check that DESTINATION_DIR is set and writable
• Review logs under the data directory for specific error messages
• Ensure the download client reports the correct download path inside the container

Stuck downloads after a restart

Issues remain “Snatched” or post-processing never finishes after a crash.

Fix:

• Restart Comicarr once and check logs for [RECOVERY] / [JOURNAL] lines
• Allow a full stop_grace_period (Compose defaults to 30s) so workers can flush the pipeline journal
• Confirm the download client still has the item (or completed history) and that paths are writable
• See Download Pipeline & Recovery

An import that Activity says succeeded never reached the library

The issue shows as imported, but the files are still sitting in the download directory.

Cause: Versions before v0.34.0 could close a download out as post-processed based on download-history state alone, without checking that anything was actually placed in the library. Those rows then looked finished to the pipeline, so no later startup revisited them.

Fix: Update to v0.34.1 or later and restart once. Startup recovery re-examines finished pipeline records the library contradicts and puts them back through the normal path, re-running the import when the completed folder still resolves. Anything it cannot resolve lands in Needs attention as "download finished but was never imported into the library", with the files ready for a manual import. See Pipeline & Recovery.

Completed NZB downloads land in Needs attention with immutable_payload_conflict:provider

Every finished NZBGet download is quarantined instead of imported.

Cause: The pipeline recorded the same download's provider two ways, as DrunkenSlug (newznab) at grab time and plain DrunkenSlug at completion, so the guard against a download changing identity mid-flight fired on all of them.

Fix: Update to v0.34.1 or later. Both spellings resolve to one provider, and records written under the old spelling are reconciled on the next startup.

Migration issues

The Mylar3 migration fails or reports errors.

Fix:

• Verify mylar.db is mounted and accessible (Docker often uses /mylar3)
• Check file permissions: the container user must be able to read mylar.db and related SQLite sidecar files
• Run a preview migration first
• Check the Comicarr logs for specific table errors

FlareSolverr not working

Direct download providers that require JavaScript rendering fail.

Fix:

• Set ENABLE_FLARESOLVERR and FLARESOLVERR_URL in config.ini; there is no Settings tab for them
• Confirm FlareSolverr is reachable from the Comicarr container (e.g., http://flaresolverr:8191)
• Check that the FlareSolverr container is running:

  docker logs flaresolverr

AI features not working

AI features are enabled but not producing results, or the AI status shows errors.

Fix:

• Check the circuit breaker state in Settings → AI. If open, the endpoint may be unreachable
• Verify your API key and model with Test Connection
• Non-localhost endpoints should use HTTPS; HTTP is only allowed for local addresses
• Review token usage. Once the daily limit is reached, AI features pause until reset
• Check the dashboard activity feed for specific error messages
• For local models (Ollama, LM Studio), ensure the service is running and the model is pulled

AI circuit breaker stuck open

The circuit breaker shows an error state and won't recover.

Fix:

• The circuit breaker transitions to half-open after the cooldown period (default: 300 seconds)
• Verify the underlying issue is resolved (endpoint reachable, API key valid)
• Wait for the cooldown to expire. A successful test request closes the circuit
• As a last resort, restart Comicarr to reset the circuit breaker state

FAQ

Where is the config stored?

Docker: /config/comicarr/config.ini inside the container (host: ./config/comicarr/config.ini with the default volume). Manual install: <datadir>/config.ini (defaults to the app directory unless --datadir is set). Encryption keys: <datadir>/.secure/.

How do I reset my password?

Clear the configured credentials from config.ini (username/password fields under the interface section) or remove them carefully and restart so first-run setup runs again. Prefer restoring from a known-good backup if unsure.

What is the default port?

8090. Change it with the HTTP_PORT setting in config.ini or by mapping a different host port in Docker.

Does Comicarr support CBR files?

Yes. Comicarr reads CBR files natively. If you prefer CBZ, enable CBR2CBZ_ONLY under post-processing / media settings to convert CBR to CBZ during post-processing.

How do I use the API?

Most UI API routes use a session cookie after login. A persistent API key (regenerate under Settings → API & providers) works for library browse GETs such as /api/watchlist. See the API documentation. Real-time UI updates use SSE events.

How do I read the logs?

Settings → Logs shows the tail of comicarr.log in the browser. Filter by severity, pull 200 / 1,000 / 5,000 lines, and copy straight into a bug report. Secrets are redacted server-side. The level dial sits above it and applies immediately, with no restart. New log (v0.35.0) rolls the file over so the viewer shows only what happens from that point on, archiving the previous log. See Logging.

How do I turn up logging?

Set the level to 2 · Debug in Settings → Logs, or pass --log-level debug, or set COMICARR_LOG_LEVEL=2 in your compose file. A startup argument beats the environment variable, which beats the saved setting. Level 0 still writes warnings and errors.

How do I generate a support bundle?

Two different artifacts, for two different situations:

See Care Package & Support Bundle. Review either archive before attaching it to a public issue.

Where do I configure download clients and indexers?

Newznab and Torznab indexers are fully editable under Settings → Search (Torznab since v0.33.0), and SABnzbd under Settings → Download clients. NZBGet, blackhole, and every torrent client are configured in config.ini.