Project diagnostics
:::caution Beta Doctor is currently in beta. It provides focused, versioned diagnostics and never claims that the whole application is secure. :::
Run Doctor inside a generated project whenever setup, startup, sign-in, refresh, OAuth, or deployment behavior needs investigation:
npx create-authenik8-app@latest doctor
The default mode is fast and read-only. It detects the nearest Authenik8 project, validates generated structure and the project manifest, checks runtime and package-manager compatibility, validates environment and signing-key semantics, inspects Prisma when configured, and verifies the configured Redis mode. Doctor does not require a Docker daemon; Express presets only require their generated Compose file to remain present.
The generator has a separate internal auth-boundary validation. Doctor is a standalone command that developers can run throughout the project lifetime.
Deep and production checks
Run isolated Redis capability checks and real authenik8-core authentication checks:
npx create-authenik8-app@latest doctor --deep
Deep mode creates a unique authenik8:doctor:<uuid> namespace. It checks Redis write, read, expiry, deletion, conditional locking, and atomic scripts. It then exercises access-token issuance and verification, refresh rotation, replay rejection, concurrent refresh rejection, session revocation, invalid signatures, and public JWKS stripping through the installed engine. It does not use real user identities, and temporary keys are cleaned up.
Run deep checks plus production policy:
npx create-authenik8-app@latest doctor --production
Production mode rejects local-only service URLs, in-process Redis, insecure browser cookies, wildcard origins, and other development assumptions. Doctor never applies development migrations or rotates signing keys in production.
One diagnostic and explanations
Every diagnostic has a stable A8-<CATEGORY>-<NUMBER> ID. Run one check and its prerequisites:
npx create-authenik8-app@latest doctor --check A8-DB-003
Explain a diagnostic without running project code:
npx create-authenik8-app@latest doctor --explain A8-JWK-006
Failures and warnings include a summary, cause or impact when known, concrete remediation, and a targeted verification command.
Safe fixes
Preview applicable fixes without changing files:
npx create-authenik8-app@latest doctor --fix --dry-run
Apply eligible fixes and rerun affected checks:
npx create-authenik8-app@latest doctor --fix
Fixes are classified as safe, confirmation-required, or manual. Doctor previews changes, checksums affected files, captures their original contents and modes in memory, writes atomically, verifies the result, and restores captured state when verification fails. CI, JSON, and non-interactive sessions never approve confirmation-required fixes.
JSON, CI, reports, and offline use
Print versioned JSON:
npx create-authenik8-app@latest doctor --json
Use deterministic, colour-free CI output and fail on warnings:
npx create-authenik8-app@latest doctor --ci --production --strict
Skip live service checks when CI intentionally has no database or Redis:
npx create-authenik8-app@latest doctor --ci --offline --strict
In a clean checkout without .env, this offline CI mode validates .env.example and holds its ephemeral ES256 key, refresh secret, and enabled-provider credentials only in memory. It never writes those values to disk. Explicitly mapped secret pairs are still validated and incomplete mappings fail closed.
Write a sanitized support report:
npx create-authenik8-app@latest doctor --report
Reports are written to .authenik8/reports/doctor-<timestamp>.json. Redaction covers configured secrets, credential-bearing URLs, JWTs, cookies, authorization data, private PEM material, and private JWK fields. Report generation refuses to write when safe redaction cannot be guaranteed.
Exit codes
| Exit code | Meaning |
|---|---|
0 | Checks completed with no failures |
1 | A diagnostic failed, or a warning exists in strict mode |
2 | Invalid usage or no Authenik8 project detected |
3 | Doctor encountered an internal error |
4 | A requested automatic fix failed |
5 | A safely redacted report could not be generated |
Failed prerequisites cause dependent checks to skip so the first actionable failure remains clear. Doctor never claims that the entire application is secure.
Project manifest
Current projects include a source-controlled authenik8.json. It records the generator and engine versions, preset, runtime, package manager, database, Prisma, OAuth providers, and PM2 choice. It never records secrets, tokens, environment values, or timestamps.
Doctor can structurally inspect older projects without a manifest, but version-aware upgrades require a valid manifest.
If a diagnostic indicates a security vulnerability, use the private vulnerability-reporting process instead of opening a public issue. Review any Doctor report before attaching it.