Why Supabase self‑hosted email appears disabled in the dashboard but still works

by

Summary

In this postmortem, we analyze a common discrepancy in self-hosted Supabase environments where the administrative dashboard reports a service (Email/SMTP) as “disabled” even though the underlying service (GoTrue/Auth) is fully functional and successfully delivering emails. This is a state-sync illusion caused by the separation of the control plane (Dashboard) and the data plane (Auth Service).

Root Cause

The issue stems from a decoupling of configuration sources. In a managed Supabase environment, the Dashboard and the Auth service share a unified configuration backend. In a self-hosted Docker Compose setup:

  • Configuration Divergence: The Dashboard UI reads its “enabled/disabled” state from a specific metadata layer or a hardcoded default, whereas the Auth service (GoTrue) relies strictly on Environment Variables passed via Docker.
  • Dashboard Logic: The Supabase Dashboard is often configured to display status based on what it expects to find in a managed cloud configuration. In self-hosted mode, the dashboard does not have a direct “write-back” mechanism to your .env file or Docker engine.
  • The “Source of Truth” Conflict: The Source of Truth for email functionality is the GOTRUE_EXTERNAL_EMAIL_ENABLED variable inside the supabase-auth container. The Dashboard is merely a visual observer that is failing to observe the actual running state.

Why This Happens in Real Systems

This phenomenon is a byproduct of Distributed Systems Architecture:

  • Control Plane vs. Data Plane: The Dashboard acts as a management interface (Control Plane), while the Auth container is the worker (Data Plane). If the interface isn’t explicitly programmed to query the live environment variables of a container, it will default to a “safe” or “initial” state.
  • Hardcoded Defaults: Many UI components are designed with “Cloud-First” mentalities. They assume that if they didn’t explicitly toggle a bit in a database, the feature is off.
  • Abstraction Leaks: When we move from a Managed Service (SaaS) to Self-Hosted (IaaS/PaaS), the abstractions break. The UI expects a specific API response to confirm a feature is “on,” but in self-hosting, that API response might not exist or might not be implemented.

Real-World Impact

  • Operational Confusion: On-call engineers may waste critical time troubleshooting “broken” email flows that are actually working perfectly.
  • False Alarms: Automated health checks or manual audits might flag the system as non-compliant or misconfigured.
  • Deployment Friction: It creates uncertainty during scaling or migration, as engineers cannot trust the visual telemetry provided by the management tools.

Example or Code

The configuration that actually controls the logic is located in your .env file, not the Dashboard UI:

# This is the ONLY variable that matters for functionality
GOTRUE_EXTERNAL_EMAIL_ENABLED=true

# SMTP Configuration
GOTRUE_SMTP_HOST=smtp.gmail.com
GOTRUE_SMTP_PORT=587
GOTRUE_SMTP_USER=your-email@gmail.com
GOTRUE_SMTP_PASS=your-app-password
GOTRUE_SMTP_SENDER_NAME=Supabase Auth

How Senior Engineers Fix It

A senior engineer ignores the “visual noise” and focuses on verifiable telemetry:

  1. Verify the Data Plane: Use docker exec to confirm the running process has the correct environment variables.
  2. Test the Side Effect: Perform a functional test (e.g., trigger a Magic Link) and inspect the actual SMTP logs or the mailbox.
  3. Accept the UI Limitation: Recognize that the Dashboard is an unreliable indicator of state in self-hosted environments.
  4. Implement Proper Monitoring: Instead of relying on a Dashboard toggle, set up actual monitoring (e.g., Prometheus/Grafana or Log aggregation) to track email_sent_success metrics.
  5. Documentation: Update the internal runbooks to state: “Dashboard email status is a known visual bug; rely on Auth container logs for truth.”

Why Juniors Miss It

  • UI Dependency: Juniors often treat the Dashboard as the Source of Truth. If the screen says “Disabled,” they assume the feature is dead.
  • Symptom vs. Cause: They attempt to “fix” the UI or search for a “Save” button in the Dashboard that doesn’t exist for self-hosted setups, rather than looking at the underlying infrastructure.
  • Lack of Layered Thinking: They fail to distinguish between the Management Layer (UI) and the Execution Layer (Docker Containers/GoTrue).

Leave a Comment