QR Code Gone: Authelia's Silent Fallback Mode Revealed

When Your QR Code Hides in Plain Sight: The Authelia Debug That Saved the Day

The borisovai-admin project needed two-factor authentication, and Authelia seemed like the perfect fit. The deployment went smoothly—containers running, certificates in place, configuration validated. Then came the critical test: click “Register device” to enable TOTP, and a QR code should appear. Instead, the browser displayed nothing but an empty void.

I started in the obvious places. Browser console? Clean. Authelia logs? No errors screaming for attention. API responses? All successful HTTP codes. The registration endpoint was processing requests flawlessly, generating tokens, doing exactly what it should—yet somehow, no QR code materialized on screen. The system was working perfectly while simultaneously failing completely.

Thirty minutes into chasing ghosts through log files and configuration documents, something clicked. I noticed a single line that had been hiding in plain sight: notifier: filesystem. That innocent parameter changed everything.

The story behind this configuration is deceptively simple. When Authelia is deployed without email notifications properly configured, it doesn’t crash or loudly complain. Instead, it shifts gracefully to a fallback mode designed for local development. Rather than sending registration links via SMTP, SendGrid, or any external service, it writes them directly to the server’s filesystem. From Authelia’s perspective, the job is done perfectly—the registration URL is generated, secured with a cryptographic token, and safely stored in /var/lib/authelia/notifications.txt. From the user’s perspective, they’re staring at a blank screen.

The fix required thinking sideways. Instead of expecting Authelia to magically display the QR code through some non-existent UI mechanism, I needed to retrieve the notification directly from the server. A single SSH command revealed everything:

cat /var/lib/authelia/notifications.txt

There it was—the full registration URL with the token embedded. I opened it in a browser, and suddenly the QR code materialized. Scan it with Google Authenticator, and the entire flow worked perfectly.

Here’s what made this moment instructive: Authelia’s design isn’t a bug or a limitation—it’s a deliberate choice for development environments. The filesystem notifier eliminates the need to configure SMTP servers, manage API credentials for email services, or spin up complex testing infrastructure. It’s honest about what it’s doing. The real lesson is that configuration choices have invisible consequences. A setting that makes perfect sense for development creates silent failures in testing. The system works flawlessly; the alignment between system behavior and user expectations simply vanishes.

The fix was immediate—reconfigure the notifier to use proper email or document the behavior clearly. Either way, the next developer wouldn’t need to hunt QR codes through the filesystem like digital treasure maps.

---

A programmer puts two glasses on his bedside table before going to sleep: a full one in case he gets thirsty, and an empty one in case he doesn’t. 😄