QR Code Mystery: Why Authelia's Registration Silently Failed

When Your QR Code Hides in Plain Sight: Debugging Authelia’s Silent Registration

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 against the docs. Then came the test: click “Register device” to enable TOTP, and a QR code should appear on screen. Instead, the browser displayed nothing but an empty canvas.

The obvious suspects got interrogated first. Browser console? Clean. Authelia logs? No errors. API responses? All successful. The registration endpoint was processing requests correctly, generating tokens, doing exactly what it should—yet somehow, no QR code materialized on the user’s screen. It was like the system was working perfectly while simultaneously failing completely.

After thirty minutes of chasing ghosts through log files, something clicked: the configuration was set to notifier: filesystem. That innocent line in the config file changed everything.

When Authelia is deployed without email notifications configured, it doesn’t scream about it or fail loudly. Instead, it silently shifts to a fallback mode designed for local development. Rather than sending registration links via SMTP or any external service, it writes them directly to a file on the server’s filesystem. From Authelia’s perspective, the job is done perfectly—the QR code URL is generated, secured with a 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 display the QR through some non-existent UI element, the answer was to retrieve the notification directly from the server. A single SSH command—cat /var/lib/authelia/notifications.txt—exposed the full registration URL. Open that link in a browser, and there it was: the QR code that had been sitting on the server all along, waiting to be discovered.

What makes this moment worth noting is what it reveals about infrastructure thinking. Configuration isn’t just about making things work; it’s about making them work the way users expect. Authelia was functioning flawlessly. The system was honest about what it was doing. The disconnect happened because the notifier configuration wasn’t aligned with the deployment context.

The solution meant either reconfiguring Authelia to use proper email notifications or documenting this filesystem fallback for the admin team. Either way, the mystery evaporated once we understood that sometimes the most elegant features of a system aren’t bugs—they’re just hiding in files instead of browsers.

A comment was added to the project configuration explaining the filesystem notifier behavior and linking to the retrieval command. Next time a developer encounters this scenario, they won’t spend half an hour wondering where their QR code went.

Why did the Authelia developer get stuck in troubleshooting? They were looking for notifications in all the wrong places—literally everywhere except the filesystem!