Skip to main content

Common issues

Start with Doctor because it reports structural, dependency, environment, and service failures without printing secret values:

npx create-authenik8-app@latest doctor

Redis connection refused​

For local development, confirm REDIS_URL=memory://. For an external service, verify REDIS_URL or REDIS_HOST, REDIS_PORT, and REDIS_PASSWORD, then rerun npx create-authenik8-app@latest doctor --check A8-REDIS-001. Docker is optional.

Prisma Client did not initialize​

Use npx create-authenik8-app@latest doctor --check A8-DB-003 to verify that DATABASE_URL matches the generated Prisma provider. Then run npm run db:migrate; Prisma's output distinguishes connectivity, authentication, pending migration, and failed migration states.

Signing key configuration is invalid​

Confirm that AUTHENIK8_SIGNING_JWKS is valid JSON containing ES256 P-256 keys with unique kid, x, and y fields. AUTHENIK8_ACTIVE_KID must select a key that also includes the private d field.

Do not generate a new key every time the process starts. Restore the persisted key from the deployment secret manager.

Issuer or audience is missing​

Set valid AUTHENIK8_ISSUER and AUTHENIK8_AUDIENCE values. Tokens are bound to both values and verification fails when they do not match.

Cannot POST /auth/login​

The login route exists only in email and password and OAuth Express presets. JWT-only projects do not include local credential login. Fullstack mounts the route at /api/auth/login and requires the generated CSRF flow.

OAuth redirect URI mismatch​

Copy the exact callback URI from .env to the provider dashboard, including protocol, port, and path.

OAuth provider is not configured​

Preview and apply the matching recipe instead of hand-editing generated auth files:

npx create-authenik8-app@latest add oauth-github --dry-run
npx create-authenik8-app@latest add oauth-github

Then replace the generated provider credential placeholders and rerun Doctor.

Doctor reports a stable diagnostic ID​

Explain it without running the project:

npx create-authenik8-app@latest doctor --explain A8-JWK-006

Run only that diagnostic and its prerequisites with npx create-authenik8-app@latest doctor --check <ID>. Preview eligible repairs with npx create-authenik8-app@latest doctor --fix --dry-run.

Invalid, expired, or reused refresh token​

Authenticate again and replace the stored refresh token. Rotation intentionally invalidates the previous token.

Concurrent refresh detected​

Send only one refresh request at a time and share its result with waiting client requests.

Manifest drift detected​

Review the reported architecture difference. Restore accidental changes from source control. If the change was intentional, update authenik8.json in the same audited change rather than editing it to silence Doctor.

Port 3000 is already in use​

Stop the existing process or change the generated application's PORT value.

npm error EALLOWSCRIPTS when running the CLI​

Recent npm versions block lifecycle scripts during project-scoped installs. When you see:

npm error code EALLOWSCRIPTS
npm error --allow-scripts is not allowed in project-scoped installs. Add the entries to the "allowScripts" field in package.json, or to .npmrc, instead.

Do not pass --allow-scripts to the command. Instead, add the entries to the allowScripts field in package.json:

{
  "allowScripts": {
    "create-authenik8-app": true
  }
}

or add them to .npmrc:

allow-scripts=create-authenik8-app

Then rerun the install command.