Skip to content

Troubleshooting

Jump to bottom
sassanix edited this page Oct 30, 2026 · 5 revisions

wrench icon Troubleshooting

Start with the logs — most problems show up there:

docker compose logs warracker
docker compose logs warrackerdb
docker compose ps

Contents

The app container won't start

  • Check that the database container is healthy first: docker compose ps should show warrackerdb as healthy. The app waits for the database (up to 30 attempts) and exits if it never becomes ready.
  • Check that the database settings match between the two services: DB_HOST, DB_NAME, DB_USER, and DB_PASSWORD in the app must match the POSTGRES_* values of the database container. See Configuration.
  • Look for Running database migrations... in the app log. If migrations fail, the app cannot start — check the error lines above it, which usually point at the database connection.

I can't log in / OIDC login loops

  • For local accounts, check the password and that the account is active (an admin can check this in User Management).
  • For OIDC, check the provider settings one by one: issuer URL, client ID, and client secret. The redirect URI you register at your provider must be your public URL plus /oidc/callback (for example, https://warracker.example.com/oidc/callback).
  • FRONTEND_URL and APP_BASE_URL must match your public URL, or redirects and email links break. See Configuration and Reverse Proxy.
  • The "skip login screen" option only works together with OIDC-only mode. If you enabled one without the other, nothing happens — that combination is by design.
  • If you locked yourself out of OIDC-only mode, set OIDC_ONLY_MODE=false in your .env, recreate the container, and log in with a local account.

I forgot my password and email isn't set up

Password reset needs working SMTP. If you never configured email, there is no self-service recovery and an admin cannot reset your password from the panel. Prevention is the fix: keep a second admin account, and configure SMTP (see Configuration and Security).

Notifications aren't arriving

Work through this list in order:

  1. Is the notification channel enabled? Email needs SMTP settings; Apprise needs APPRISE_ENABLED and at least one URL.
  2. Is the warranty's expiry within one of your thresholds? Email uses your per-user "Expiring Soon Days"; Apprise uses the site-wide Notification Days.
  3. Is the scheduled time right? Check the notification time and timezone in Settings — a wrong timezone looks exactly like "notifications never arrive".
  4. Have you already been notified for this threshold? Notifications are sent once per threshold per warranty per channel, so a second alert for the same threshold will not come.
  5. Use the test buttons: "Send Warranty Notifications" (email) and "Test URL" (Apprise) in Settings, and check the spam folder.
  6. Check the logs for delivery errors.

See Notifications for the full rules.

Paperless-ngx browse is empty or the connection fails

  • Use the admin test buttons in Settings: Test Connection, Debug Config, and Test Upload. They tell you whether the URL and token work at all.
  • The Paperless URL must be reachable from inside the Warracker container. If both run in Docker, use the Paperless container/service name (for example, http://paperless:8000), not localhost — localhost inside the Warracker container means Warracker itself.
  • Non-admin users only see Paperless documents they own or that are linked to their own warranties. An empty browser for a regular user is often correct behavior, not a connection failure. See Paperless-ngx.

Uploads fail

  • Check the file type: product photos accept PNG, JPG, and WebP; invoices and manuals accept PDF, PNG, JPG, and JPEG; other files accept ZIP and RAR.
  • Check the size: the default limit is 16 MB in the compose file (32 MB in the code default). A 413 error means the file is over the limit. Raise MAX_UPLOAD_MB and NGINX_MAX_BODY_SIZE_VALUE together — the nginx value must match or exceed the app value. See Configuration.
  • Check that the uploads volume is writable and not full.

The page looks old after an update

Static files are cached for up to a year, so your browser may show the previous version after an update. Hard-refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS). If that does not fix it, clear the site's cached files and reload.

The Scope (Personal/Global) switch is missing

The switch only appears when an admin has enabled Global View in Settings. If it is off, every user sees only their own warranties. See Authentication.

CSV import fails

  • Every row needs a product name and a purchase date in YYYY-MM-DD format, plus either a warranty duration or the lifetime flag.
  • A single field larger than 128 KB is rejected, and the whole import reports the error — check the row the log points at.
  • Re-importing the same file creates duplicates unless you delete the old warranties first; import does not merge. See the User Guide CSV section.

I can see another user's warranties

That is the global view, and it is intentional for family/team instances: when Global View is on, every user can see every warranty, including downloading invoices, manuals, and photos. Claim documents and "other documents" are never shared through the global view — they stay owner/admin-only. If you did not intend this, turn Global View off in Settings, or switch it to "Admin Only". See Authentication.

Error numbers

When something fails, the app answers with an HTTP status number, and the interface or the log shows it. This is what each number means in Warracker, and what to do about it.

Number Meaning What to do
400 Bad request — something in what was sent is invalid: a required field is missing, the product name or serial number is over 255 characters, a tag name is over 50 characters, the expiration date is before the purchase date, an uploaded file type is not allowed, or a CSV field is over 128 KB. Fix the field the error message names and try again — the message itself says which rule was hit.
401 Unauthorized — you are not logged in, or your session has expired. Log in again. If it starts right after the container was recreated, the SECRET_KEY was not preserved and old sessions no longer verify — see Configuration.
403 Forbidden — you are logged in, but not allowed: the warranty or document belongs to another user, the action is admin-only, or you tried to link a Paperless-ngx document that belongs to another user. Use the owning account, or ask an admin. Claim documents and "other documents" stay owner/admin-only even with Global View on.
404 Not found — the warranty, claim, or document does not exist, or exists but is not visible to your account. The app answers 404 in both cases on purpose, so it never reveals whether another user's data exists. Check you are logged in as the right user, and that the link or ID is correct.
409 Conflict — something with that name already exists: a username or email address at registration, or a tag name on your account. Pick a different name or email address.
413 File too large — an upload is bigger than the server's limit (MAX_UPLOAD_MB, 16 MB in the shipped compose file). Shrink the file (phone photos are the usual cause), or raise MAX_UPLOAD_MB in .env (and NGINX_MAX_BODY_SIZE_VALUE with it) and recreate the container.
500 Server error — something failed inside the app. Check docker compose logs warracker for the error at the time it happened, and include those lines if you open an issue.
502 Bad gateway — this one comes from nginx or your reverse proxy, not the app: the app container is down, still starting, or unreachable. Run docker compose ps to check the container is up, give it a few seconds after a restart, and check the proxy points at the right port (8005 on the host, 80 inside the container). See Reverse Proxy.
503 Service unavailable — a feature you called is not available: the Paperless-ngx integration is disabled or unreachable, Apprise notifications are not available, or the health check cannot reach the database. Check the feature is enabled in Settings and its service is running. For Paperless, see the Paperless section above.

Named error codes

Some 400 and 403 answers also carry a code field, visible in API responses and in the logs:

Code Meaning
file_type_not_allowed The uploaded file's extension is not allowed for that upload (product photos: .png, .jpg, .jpeg, .webp).
product_name_too_long The product name is over 255 characters.
serial_number_too_long The serial number is over 255 characters.
csv_field_too_large A field in the CSV import is over 128 KB.
expiration_before_purchase The expiration date is before the purchase date.
invalid_claim_status The claim status is not one of the valid claim statuses.
paperless_document_not_owned (403) The Paperless-ngx document belongs to another user; only its owner, or an admin, can link it.

Still stuck?

Open an issue on GitHub with your version, install method, steps to reproduce, and the relevant log lines — see FAQ.

Clone this wiki locally