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 (especially in Docker quiet mode).

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:

• Verify host, port, and credentials in config.ini (the Settings → Download clients tab is read-only status)
• 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:

• Verify Newznab/Torznab provider configuration in config.ini
• Confirm API keys are valid for each provider
• Check USENET_RETENTION (default: 3500 days) — reduce if your provider has shorter retention
• Review provider order settings so preferred providers are enabled
• Check application logs for provider-specific errors

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

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 / FLARESOLVERR_URL in config.ini (not a dedicated Settings tab)
• 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 — if 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 will close 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 can read CBR files natively. If you prefer CBZ format, enable CBR2CBZ_ONLY (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 generate a support care package?

python3 Comicarr.py --datadir /path/to/data maintenance --carepackage
# or: maintenance -care

See Care Package. The zip is written under the logs directory with secrets redacted.

Where do I configure download clients and indexers?

Primarily in config.ini. The Download clients Settings tab shows current client labels as read-only. Search provider Newznab/Torznab hosts are not fully editable in the Search tab (quality/size filters are).