Troubleshoot

Start with the failing request and the result you expected. For the local walkthrough, Verify access lists the four expected outcomes and how to reproduce each one.

Caddy does not recognize security or authenticate

Run list-modules against the same executable you use to start the server. It must include security, http.handlers.authentication, and http.handlers.authorization. A standard Caddy build does not include them.

Follow Install and verify. If the module is present but a subdirective is rejected, record security version and compare the configuration with that release. An example for another version may use removed syntax.

The local demo will not start

Read the first startup error in the server terminal.

Observation	Check
Address already in use	Another process is listening on port 9080. Stop the earlier demo process, or choose another available port and update both the site address and policy auth URL.
Signing key error	Generate and export AUTHCRUNCH_DEMO_SECRET in the terminal that starts the server, as shown in the walkthrough.
Cannot open or create the store	Start from the demo directory. Check that its data directory exists and is writable by the process.
Caddyfile parse error	Copy the complete file, including the global block and site block. Run adapt to isolate parsing before attempting login.

The demo disables Caddy's admin endpoint. To change its configuration, use Ctrl+C and start it again; a reload command cannot reach a disabled endpoint.

The browser returns to login

First distinguish a missing login from an invalid token:

1. Use http://localhost:9080 consistently for the local example. Do not switch between localhost and 127.0.0.1.
2. Confirm that you completed both the username and password steps. The tested flow lands on the portal's Applications page; choose Example app there.
3. In browser developer tools, check that the login sets a cookie and that the next request to /app sends it. Do not copy token values into public reports.
4. Confirm that the portal and policy use the same signing/verification key. If you regenerated the demo secret, sign in again to get a token signed with it.

For a deployed site, check the cookie domain and path, HTTPS, the policy's auth URL, and token discovery. A cookie that the browser does not send cannot satisfy the policy.

Login works, but the app returns 403

For the local demo, Bob is supposed to receive 403. The policy requires app/member, which only Alice has. This separates a successful login from a successful authorization decision.

If Alice is denied, compare the active Caddyfile with the complete example. Check her roles and the policy's allow roles entry, then test from a fresh login. If you have been editing an existing user database, repeat the original example in a new directory to separate stored state from configuration.

For your own deployment, compare the authenticated user's claims with the policy rules. Check rule order and any path restrictions before changing permissions.

The app is reachable without signing in

Test with curl -i without a cookie jar, or a new private browser window. Confirm the request matches the protected route and that authorize runs before the application handler. In the learning example, /app and /app/* are protected; / deliberately returns a public status message.

For a reverse proxy deployment, also check that users cannot reach the upstream application directly through another public address or port.

There is an extra local administrator

When a new local store has no administrative user, AuthCrunch can create a bootstrap administrator. With the demo's default environment, its username is webadmin and its password is generated; the Alice and Bob tests do not use it. Do not assume that the two configured demo accounts are the only store records.

Review local identity store configuration before using local accounts in a deployment.

An external provider redirects back but login fails

Check the callback for the configured realm, not merely the provider's configuration name. The public origin and portal mount must agree with the registered callback. Inspect the specific failed trust check before changing scopes or retries.

Observation	Follow-up
Discovery fails or the provider is not ready	Verify DNS, certificate trust and copied discovery URL; startup/retry settings are separate from code-exchange retry
OIDC issuer, audience, nonce or signing key fails	Compare the actual issuer/client and upstream token trust; the accepted metadata-disable flag does not suppress a configured fetch
Login succeeds but a group grants unexpected app access	Clear reserved internal roles before controlled transforms; inspect the driver's actual claim source
A SAML POST lacks usable state	Start from the portal GET entrance, preserve RelayState and use HTTPS; check the bound SAML flow, callback and dedicated cookie
Nextcloud redirects but no identity is created	The native Nextcloud driver boundary is incomplete; an opaque access token is not a portal identity

Do not disable signature/nonce checks or add app permissions to conceal a provider setup failure. Test a fresh valid login and a signed-in nonmember.

Registration or email behaves differently from the template

Email acknowledgement writes a separate registration dropbox; it does not create an active account. Check registration for confirmation failure, replay and administrative delivery behavior.

The released messaging transport uses embedded registration templates even when a custom path is configured. SMTP requires the correct plaintext/implicit-TLS mode; it does not upgrade with STARTTLS. A BCC header does not add a delivery recipient in this implementation. Verify actual delivery with private test recipients instead of assuming parser acceptance proves it.

A feature is visible in source but missing from my binary

Compare the integration revision, bundled library and compiled modules with Feature availability. New library APIs, accepted configuration names and partial handlers do not all establish a working Caddy integration. For example, AWS SSO has metadata/menu support without an implemented assume-role assertion, while certificate login is separate from Caddy's transport-level mutual TLS.

Ask for help with a reproducible case

For renewable local sessions, check the status table in Refresh sessions. For a restart or storage error, check the ownership, permissions and stop/start requirements in Persistent runtime state. Use Authentication logging to capture a relevant diagnostic without changing the access decision.

Open an issue with:

• The Caddy and AuthCrunch versions and how you installed the binary.
• The expected result, actual HTTP status, and the step that failed.
• A minimal Caddyfile and the relevant server error, with secrets removed.
• Whether the local walkthrough works in a fresh directory.

Remove passwords, tokens, cookies, private keys, and provider secrets before sharing configuration or logs.