Troubleshooting

Start with the failing layer

Record application/Android versions, approximate time, action and error. Check docker compose ps, API logs and worker logs before resetting data. /api/health is a lightweight API signal; it does not verify all dependencies or catalogs.

Symptom	Likely checks
API refuses startup	TCG_SECRET_KEY length ≥32, database reachability, migration error
Browser login immediately disappears	HTTPS/TCG_COOKIE_SECURE, public URL and proxy headers
Empty catalog on first install	Worker running, first imports still active, selected games/languages
Manual jobs remain queued	Worker stopped, queue/log error, database access
One missing image	Upstream image URL, language fallback, image report and refused-download state
One missing card	Correct market, catalog progress, targeted refresh, source coverage
Old prices	Latest price job, source key/quota, printing identifiers, finish
“Administrator only”	Account role; normal accounts cannot open admin APIs
Stock conflict / 409	Wrong variant, too many removals, undo already applied, concurrent change
Import rejected	UTF-8, exact headers, row errors, unique set/printing match
HTTP 413	5 MiB CSV limit, overall request-body limit, reverse proxy limits
HTTP 429	Sign-in/request limiter or upstream quota; inspect Retry-After and source logs
HTTP 503 maintenance	Health maintenance field, running catalog job, latency/load
HTTP 500	Server traceback at the corresponding time

SSO sign-in fails

Check discovery reachability from the API, exact issuer, client ID/secret, strict redirect URI, signature algorithm and selected signing key. Confirm clocks are synchronized. A browser able to reach the IdP does not prove the backend can reach discovery/token/JWKS endpoints.

For Authentik, HS256 is refused; select an asymmetric signing certificate/key. For groups, inspect actual claim names and group strings, requested scopes and allowed/admin group lists. Do not paste tokens or client secrets in public issues.

Web works but Android SSO does not

Confirm MOBILE_CLIENT_ID is set, the client is public with PKCE S256, and its redirect URI matches the installed app (fr.zukan.app:/oauth2redirect or debug .dev). The mobile and web clients must advertise the same issuer.

An empty mobile collection can indicate a different account or issuer/subject, not lost inventory. Compare the account and server shown in Settings.

Android cannot connect

Check DNS/LAN routing, URL scheme, port and certificate chain. Never use the server's localhost address from the phone. A browser can hide missing-intermediate problems that Android reports. HTTPS on a plain HTTP port produces a TLS error rather than an application login error.

Scan gives wrong/no results

Use the correct market and OCR script. Reduce glare, include the name and collector number, and wait for stable text. Inspect the detected hint text. An exact set/number match is stronger than a partial name match. Try manual search to distinguish OCR failure from missing catalog data.

CSV-specific problems

An informational name cannot resolve multiple printings with the same set and number. Use an exported external printing ID when necessary. Blank notes/price cells do not clear stored values. Add mode is not idempotent. A dry run validates rows but does not reserve stock for later removals.

Image permissions after restore

The entrypoint changes ownership of the top-level image folder. Nested files copied as root or from another host can still be unwritable; inspect ownership and correct it for the service user. Do not delete the image cache as the first response, because source quotas may make rebuilding slow.

Forgotten administrator password

Enable local login if needed, recreate the API, and run docker compose exec api zukan create-admin recovery-admin interactively. Bootstrap .env settings do not reset an existing database's users.

Useful evidence for an issue

Provide source SHA/image tag, server/Android versions, expected versus actual result, reproduction steps, game/printing identifiers, job ID and redacted log excerpts. State whether the problem affects all users or one account. Exclude passwords, tokens, cookies, full configuration dumps and private collection exports unless intentionally shared through an appropriate private channel.