Errors & Troubleshooting

Docs version v1 (main) · Nauthera is pre-1.0, in a design-partner program · Updated November 4, 2026

#Error formats

/authorize sends an error to the client's callback only once it has validated the redirect URI, and some errors are answered directly even then. Apart from the problem documents above, a direct refusal carries only error: invalid_request, its error_uri and iss, whatever the cause. The reason is recorded in the audit log and on the trace, under the request id.

A browser that navigates to the main organization's /authorize or /end_session and hits an error gets an HTML page instead of the JSON body. The page does not give the reason. It shows the request id as a Reference ID; look it up in the logs and audit events. On every other path, /orgs/{slug}/authorize included, a browser navigation gets an HTML page only for a 404, 405, 429 or 5xx.

A problem document looks like this:

{
  "type": "https://nauthera.io/problems/invalid_credentials",
  "title": "Unauthorized",
  "status": 401,
  "code": "invalid_credentials",
  "detail": "invalid email or password"
}

Problems written outside an endpoint's handler also carry instance, request_id and, when the request was traced, trace_id: a rate-limit refusal, a request that cannot be read or fails validation, a repeated header, an unknown /v1/ path or organization, and a generic 500.

Branch on code, not on detail. Validation failures add an errors array with one {field, code, message} entry per field, using codes such as required, too_short, too_long, pattern, invalid_format and not_allowed. Problem documents carry no internal detail: database errors, stack traces and secrets are logged on the server and never returned.

Every response carries X-Request-ID, and X-Trace-Id when the request was traced. Quote the request id when you report a problem; it finds the matching log lines and audit events.

#Tracing a failed request

The sign-in app's error screens show the request id as a Reference ID, with a button that copies it. An administrator pastes it into the admin dashboard's Troubleshooting page, which reads every audit record carrying that id from the last 90 days and shows what happened: the record that decided the outcome, its reason, the endpoint, account, application, address, browser, trace id and session, and every record the request left, in order. It reads the audit log, so it needs the same permission as the audit log. Through the API, the same lookup is the request_id filter of GET /v1/admin/orgs/{slug}/audit-events. An id behind a proxy you trust is the proxy's, since a trusted proxy may set X-Request-ID itself.

#Problem codes

The server sends the 43 codes below, the list the OpenAPI document declares as ProblemCode. A problem with a code has type https://nauthera.io/problems/ followed by the code, which opens the code's runbook: why it happened, who is affected and what to do. A problem without one, such as a generic 500, has type: about:blank. The codes required and malformed here are not the per-field codes of the same names in errors.

#The server refuses to start

The server checks its configuration before opening any listener and names every problem it finds. The common ones:

The Helm chart runs the same checks when it renders, so most of these fail helm install with the fix attached.

These fail quietly rather than at startup:

• A --config path that does not exist is ignored, and the server starts on defaults and environment variables. Check the startup log for the configuration it loaded.
• An unset keys.encryption_key only logs a warning. See Keys & Secrets.
• An empty mounted secret file is not refused. It sets its key to an empty value, which outranks the YAML file and the environment, and no message says the file was empty. A key the startup checks require, such as mfa.encryption_key with the file provider, then fails them as if it were unset. See Configuration.

#Common problems

Sign-in is throttled for everyone at once. The server sees every request coming from your proxy's address, so all users share one rate-limit budget and one brute-force throttle. List the proxy in security.trusted_proxies; the dashboard's overview names the proxies it saw. See Configuration.

Sign-ins fail at the token exchange while Redis is down. Authorization codes live in Redis, so /authorize cannot complete and /token cannot redeem a code until Redis answers again. The rate limit does not refuse anyone for the outage: with rate_limit.backend: redis, each replica limits on its own bucket meanwhile and nauthera_rate_limit_degraded reads 1. Refresh tokens and revocations live in the database and keep working, except during the first refresh-token lifetime after an upgrade from a build that kept them in Redis, when Redis is still read. Check Redis.

The sign-in page answers 404. A sign-in must continue an application's request: the hosted sign-in screen, POST /v1/auth/sign-in and the passkey sign-in answer 404 unless they name a client_id registered in the organization, or continue the device flow. Send users through the application, or through /authorize, not to /login directly. Screens reached without an application, such as the end of an invitation, tell the user to go back to the application they came from.

redirect_uri is rejected. Redirect URIs are compared exactly, including the scheme, port, path and trailing slash, so a loopback redirect must name the port it was registered with.

/orgs/default/… answers 404 unknown_org. The main organization is served at the root only. Use /authorize, not /orgs/default/authorize.

A refresh answers invalid_grant. The refresh token was used before (refresh tokens rotate, and reuse revokes the whole family), it expired, its session was ended by a logout or an administrator, or every grant of the account was retired by a password reset, a change of second factor or an administrator ending all of the user's sessions. A suspended or blocked account is refused the same way. The description is the same for all of these on purpose. Send the user through /authorize again, and make sure your application never sends two refreshes with the same token. See Connect an Application.

A sign-in or registration POST answers 403 forbidden, "cross-site request rejected". The hosted UI's JSON endpoints accept only Content-Type: application/json from the issuer's own origin. Browsers send Sec-Fetch-Site: same-origin; same-site from a sibling subdomain is refused, and without that header Origin must equal the issuer. Serve the UI from the issuer, and don't let a proxy rewrite these headers.

A request answers 400 invalid_request about a repeated header. Authorization, DPoP, DPoP-Nonce, Cookie, Origin, Sec-Fetch-Site and Content-Type may appear only once. A proxy that appends instead of replacing one of them causes this. Each occurrence is recorded as an http.header.repeated audit event.

Users of another organization cannot sign in after a restart. The KEK was not set, so the organization's signing keys were sealed with a key that no longer exists. Set keys.encryption_key before creating organizations. Keys sealed under a lost KEK cannot be recovered. With more than one replica the failure shows before any restart: each replica makes up its own key, so the organization works only on the replica that created it. Identity provider client secrets are sealed under the same key, so sign-in through any organization's providers, the main one's included, fails the same way.

Users must re-enroll TOTP after a restart. The server ran with mfa.provider: memory, which the startup checks allow only on a loopback issuer, and only while mfa.required is off.

Native apps show the consent screen on every sign-in. A public client whose redirect URI is not https is always asked, because another app could claim the same redirect. See Sessions, Consent & Logout.

The operator reports Unreachable after certificates were renewed. The server reads its gRPC certificate, key and client CA again at each handshake, and keeps the last good material when a replacement cannot be used, logging it once. Check the server's log for that message and the renewed files themselves. The HTTP certificate, by contrast, is read only at startup.

The admin API answers 403 for a correct token. Two checks must both pass: the token carries the operation's scope, and the caller holds a role that grants the operation's permission. A refusal for a missing permission names it in the problem's detail. A user's roles are read from the database on every call, not from the token, so a token that still lists a removed role is refused, and a role added later counts without a new token. A client_credentials token's roles are the ones its admin client was provisioned with. Only a token issued to one of its organization's reserved admin clients ({slug}-admin-console, {slug}-admin-m2m) is accepted. A token acts only in the organization that issued it; reaching another organization needs a platform role (platform-viewer, platform-auditor or platform-owner) held in the main organization. A call that would change the caller's own account or a more privileged one answers 403 protected_account whatever the caller holds. Each refusal is recorded as an admin.access.denied audit event. See Admin API & Users.

A migration Job. nauthera-server maintain applies the migrations, maintains the audit partitions and exits, non-zero if a step failed. A release whose migration adds an audit index makes it build that index on every retained partition, which can take far longer than the migrations; allow for it in the Job's deadline. See Backups & Upgrades.

A privileged admin change answers 503 unavailable while sign-in works. With audit.fail_closed: true, admin and second-factor changes are refused while the audit log cannot record them. Check the database and the audit readiness check; the condition clears once audit writes succeed again.