Troubleshooting

Use this guide for common operational issues. Check Arr → {instance} → Logs and APP_BASE_PATH/logs/app.log for detailed error context.

Cannot connect to Arr instance

Symptoms: Test connection fails, preview errors, or sync logs show HTTP failures.

Checks:

1. URL — Use the hostname Praxrr resolves (Docker service name, not localhost from inside another container).
2. API key — Re-enter the key from Arr Settings → General. Confirm ARR_CREDENTIAL_MASTER_KEY has not changed without ARR_CREDENTIAL_PREVIOUS_KEYS.
3. TLS / reverse proxy — Canonical URL must reach the Arr API path. External URL affects browser links only.
4. Firewall — Allow traffic from the Praxrr container or host to Arr ports (7878, 8989, 8686 by default).

Set PRAXRR_VALIDATE_INSTANCES=true temporarily to surface startup validation errors for env-managed instances.

Sync preview fails or shows unexpected deletes

Symptoms: Preview status error, or many delete actions you did not expect.

Checks:

1. Confirm sync selections still match profiles present in the PCD.
2. Pull the PCD and review Changes / Conflicts for unresolved user ops.
3. Compare preview section errors — quality profile preview requires readable remote custom formats and profiles.
4. Verify arr_type on each entity matches the instance app.

Re-run preview after resolving conflicts. Preview is read-only and safe to repeat.

Sync succeeds but Arr looks wrong

Symptoms: Push reports success but scores or qualities differ from PCD.

Checks:

1. Confirm you synced the intended instance and section.
2. Open the profile in Arr UI — another profile or manual edit may still apply to media items.
3. Check for duplicate profile names on the Arr side from earlier manual imports.
4. Re-preview and inspect field-level diffs for scoring and cutoff fields.

PCD pull or link failures

Symptoms: Database stuck out of date, Git errors, or missing entities.

Checks:

1. Private repos — Set PRAXRR_DEFAULT_DB_TOKEN and Git username/email.
2. Local path sources — Local PCD folders may not be Git repos; commit and changes pages degrade gracefully without Git metadata.
3. Empty default URL — PRAXRR_DEFAULT_DB_URL="" disables auto-link by design.
4. Schema mismatch — Align PRAXRR_SCHEMA_REF with the PCD manifest.

Authentication issues

Mode	Common issue
AUTH=on	Reset password via admin flows; confirm session cookies reach the UI
AUTH=oidc	Verify OIDC_*, redirect URIs, and the sign-in allowlist
AUTH=local	Remember it skips auth only for local-network requests
AUTH=off	Insecure — anyone with network access can use the UI

Warning: Do not run AUTH=off on the public internet. Pair with external auth (Authentik, Authelia) if you disable built-in login.

A 403 from the OIDC callback means that identity is not on the allowlist. API clients need a valid API token in the X-Api-Key header (or ?apikey=) when auth is enabled. Create tokens in Settings → Security. A missing token is 401; a token without the required scope is 403.

CSRF or origin errors behind a proxy

Praxrr may use permissive CSRF trusted origins during development. If forms fail after tightening deployment:

1. Align the public URL with your reverse-proxy hostname.
2. Configure explicit trusted origins before production.
3. Confirm HTTPS termination preserves the Host header expected by the app.

Parser / testing unavailable

Symptoms: Custom format testing fails; parser connection errors in logs.

Checks:

1. Confirm the Praxrr app itself is healthy at GET /api/v1/health.
2. From inside the same private network namespace as Praxrr, call the parser’s GET /health. A healthy response includes status: "healthy" and a behavior version. Do not expose this private route through your public proxy.
3. For Docker, confirm the parser container is healthy, PARSER_HOST matches its Compose service name, and PARSER_PORT=5000.
4. For a standalone archive, confirm praxrr-parser (praxrr-parser.exe on Windows) is adjacent to the app binary and executable. Remove an accidental PARSER_HOST override to restore automatic child-process startup.
5. For a source checkout, run mise install and deno task dev:parser; the repository pins Go 1.26.10.

Sync and editing still work without the parser.

Parser response classes

Use HTTP status and sanitized log fields such as outcome and error_class; do not log or share raw release titles, patterns, request bodies, or regex engine errors.

Status	Meaning	Recovery
400	Malformed JSON or missing/invalid required fields	Correct the request.
413	A measured request, text, pattern, count, unique-key, or work limit was exceeded	Reduce the input; do not repeatedly retry the same payload.
415	The request is not JSON	Send application/json or application/*+json.
503	Active-request or matcher capacity is temporarily full	Honor Retry-After: 1 and retry with backoff.
500	Unexpected internal parser failure	Capture sanitized logs, restart once, then roll back if it repeats.

Regex timeouts are finite and fail closed for the affected pattern; they do not make the parser process unhealthy. Rework catastrophic patterns instead of raising limits. The compatibility contract remains .NET-compatible regex syntax, even though the current service is implemented in Go.

Parser recovery and rollback

1. Record the current app release, parser image or archive checksum, and parser behavior version from private /health.
2. Restart the parser without deleting parser caches. Same-version entries remain usable; misses are not filled until health succeeds.
3. If a new parser version is faulty, deploy the previous immutable image digest or restore the matching previous standalone archive. Do not roll back with a moving tag.
4. Verify private parser /health, then exercise one parse and one match through the Praxrr UI. Cache namespaces change with behavior versions, so old and new results cannot mix.
5. If recovery still fails, omit the parser and keep Praxrr online while collecting sanitized diagnostics; linking, editing, and syncing are unaffected.

Release provenance contains the exact artifact checksums, SBOM, behavior version, and immutable rollback identifiers. Use those records rather than reconstructing an old runtime from source.

Encrypted credential errors after upgrade

Symptoms: Instances show missing API keys or decryption failures.

Checks:

1. Same ARR_CREDENTIAL_MASTER_KEY as before upgrade, or valid ARR_CREDENTIAL_PREVIOUS_KEYS during rotation.
2. Restore from backup if the key was lost — encrypted blobs cannot be recovered without the original key.
3. Re-enter API keys in instance settings as a last resort.

Database migration failures

Symptoms: Praxrr exits on startup or logs migration errors.

Checks:

1. Disk space and write permissions on APP_BASE_PATH.
2. Do not run older binaries against a database migrated by a newer version.
3. Restore a backup and upgrade again after reviewing release notes. An in-app restore from Settings → Backups applies on the next restart, not when you click restore.

Live updates paused or not arriving

Symptoms: The Reconnecting… or Live updates paused indicator stays visible, or job and sync pages only change after a reload.

Checks:

1. Signed out — Live updates stop when your session expires. Log in again; the connection resumes on its own.

2. Reverse proxy buffering — Proxies must not buffer text/event-stream responses from /api/v1/events. For nginx:

   location /api/v1/events {
     proxy_pass http://praxrr:6868;
     proxy_http_version 1.1;
     proxy_set_header Connection '';
     proxy_buffering off;
     proxy_read_timeout 1h;
   }

   Caddy streams these responses without extra configuration.

3. Too many tabs — Over HTTP/1.1, browsers allow about 6 connections per host, and each Praxrr tab holds one for live updates. With more than 6 tabs open, page loads can stall. Close extra tabs or serve Praxrr over HTTP/2.

Pages keep working without live updates; reload to see the latest state.

Getting more help

• Architecture Overview — module boundaries
• Startup Sequence — init order and fail-fast steps
• Sync Pipeline — preview vs execution internals
• PCD System — ops compiler and value guards
• Job System — background queue and dispatcher
• Configuration — environment reference
• GitHub issues — bug reports

Include Praxrr version, arr_type, sanitized logs, and steps to reproduce when opening an issue. Never paste real API keys or master keys.