Learn Authelia - Troubleshooting & Debugging

#Introduction

Episode 28 made Authelia fast. Now the unavoidable part: the day something breaks. Authelia symptoms can be misleading — users see "page not accessible", when the root cause is deep inside the configuration. Episode 29 trains you to trace symptoms back to the root.

The key to Authelia troubleshooting is understanding the flow: browser → reverse proxy → Authelia (verify) → Redis (sessions) → database (data) → redirection. Every symptom can be mapped to one link in this chain. Start with the most frequent ones.

#Problem 1: 503 from the Reverse Proxy

The most common symptom: all applications show 502 or 503, as if nothing is alive. Yet Authelia is running. What's happening is almost always one of:

• The proxy can't reach Authelia. Check from inside the proxy: curl -fsS http://authelia:9091/api/health. Failing means a network, DNS, or dead container problem.
• Wrong verify endpoint. The proxy must call /api/verify, not the root /. Make sure the auth URL in the proxy configuration is exact.
• Timeout. Authelia is slow because Redis/database is misbehaving, and the proxy gives up before an answer arrives. Watch the authelia_request_duration metric from episode 26.

The inspection order: is the container alive? → does the health check pass? → is the network connected? → is the endpoint correct?

#Problem 2: Redirect Loop

The user logs in, succeeds, then keeps being redirected back to the login page. This is the classic symptom of a session not visible to the instance evaluating verify. Two main causes:

• Sessions not shared. Instance A receives the login, instance B evaluates the next request — and B doesn't read the same Redis. This happens when the session.redis configuration is inconsistent between instances (remember episode 24).
• The cookie never arrives. The session cookie is set for the wrong domain, or stripped by a proxy that doesn't forward Set-Cookie.

Check with browser developer tools: is the authelia_session cookie set, on which domain, and is it sent along on the verify request? If the cookie disappears mid-way, the problem is in the headers being stripped by the proxy.

#Problem 3: Session Problems

Sessions behave strangely — logging in over and over, or stopping entirely. Check this order:

• Redis not connected. Authelia fails to read/write sessions. Check the logs for redis connection error, then verify with redis-cli ping from the Authelia side.
• Session secret changed. All existing sessions become undecryptable — a mass re-login. If this happens without planned rotation, check who changed the secret.
• Expiration too short. Aggressive session.expiration and session.inactivity kill sessions too fast. Match them to user expectations and security policy.

#Problem 4: Database Problems

Authelia fails to store or read MFA data. Logs show a connection error or an encryption error:

• Connection refused. Check the host, port, username, and password in the storage block. Verify directly with psql -U authelia -h postgres -d authelia -c 'SELECT 1'.
• Wrong encryption key. A storage encryption key error when reading data means storage.encryption_key differs from when the data was written. This always leads back to an unintended rotation — restore the secrets from backup (episode 27).

#Problem 5: TOTP Failures

The user is sure their TOTP code is correct, but it's always rejected. TOTP is a function of time — a code is only valid within a 30-second window computed from the server clock. A clock skew between the Authelia server and the user's device, or the server clock drifting on its own, makes codes always wrong.

Authelia checks time via its built-in NTP. Make sure the server is time-healthy:

timedatectl status
chronyc tracking

Besides that, note totp.skew in the configuration — how many time windows (default 1) are tolerated. Raise it slightly during device transitions, but don't make it too loose; that weakens the TOTP security guarantees built in episode 9.

#Problem 6: Cookie Domain Mismatch

A session cookie is only sent for matching domains. If Authelia is at auth.example.com but the cookie is set for example.com or vice versa, the session never arrives. Multi-domain session configuration in modern Authelia is defined in the cookies block — each entry has its own domain and authelia_url. Make sure both are consistent with how the proxy routes requests.

#Validating Configuration and Health Checks

Two tools solve half the problems before touching the runtime. First, validate the configuration — Authelia rejects invalid configuration from the start, so syntax errors are caught early:

authelia validate-config --config /config/configuration.yml

Second, test access control decisions logically — faster than reloading the browser:

authelia access-control check-policy \
  --config /config/configuration.yml \
  --user arman \
  --url https://app.example.com

This command answers "what policy does this user receive for this URL?" — the best debugging tool for confusing rules from episode 6.

#Reading Logs: The Authelia Detective

When a problem gets past validation, the log is the primary witness. Raise the level to debug to see the authorization decision flow, then observe each message per step. The key questions the log answers:

• Was the verify request received? (method, path, headers)
• Was the session found? Is the cookie valid and not expired?
• What decision was made for the requested URL? (bypass, one_factor, two_factor, deny)

One pattern that often misleads: errors at the error log level on verify requests are usually the expected response for a user not logged in — verify returns 401/302 and that's normal. Don't read logs without understanding the flow; read logs while looking at the actual HTTP response.

#Closing

Episode 29 equips you with detective skills: mapping the six most common problems — 503 from the proxy, redirect loops, sessions, database, TOTP depending on time synchronization, and cookie domain mismatch — then handling each at the root, validating the configuration with authelia validate-config, testing rules with authelia access-control check-policy, and reading debug logs without misinterpreting them.

Key points:

• Map the symptom to the chain: browser → proxy → verify → Redis → database.
• 503 at the proxy = check network, health, endpoint, timeout — in that order.
• Redirect loop = sessions not shared or the cookie not arriving.
• TOTP failure = check the server clock and NTP before suspecting the user's device.
• debug logs + check-policy are the best debugging pair.

You now hold all the skills. Episode 30 — the final episode — summarizes everything in Production Checklist & Best Practices: a pre-production checklist, security and operational best practices, common traps, a recap of the journey, and the future of Authelia. See you in episode 30!