Custom Recovery Template Ignored

[kopko13]

Problem Summary:
Supabase GoTrue (Auth) consistently ignores the GOTRUE_MAILER_TEMPLATES_RECOVERY environment variable and falls back to sending the site's index.html (Site URL) as the email body, or an empty email, despite correct file permissions and configuration. This behavior persists even after explicitly patching docker-compose.yml and verifying environment variables inside the container.

Environment:

• Self-Hosted Supabase (Docker Compose)
• Image: supabase/gotrue:v2.183.0 and tested with latest
• OS: Linux

Configuration:
In docker-compose.yml, the auth service is explicitly configured with:
auth:
environment:
GOTRUE_MAILER_TEMPLATES_RECOVERY: /etc/gotrue/templates/reset_password.html
GOTRUE_MAILER_SUBJECTS_RECOVERY: "Reset Your Password"
volumes:
- ./volumes/auth_templates:/etc/gotrue/templates:Z

Verification Steps Performed:

1. File Existence & Permissions:
   • Confirmed /etc/gotrue/templates/reset_password.html exists inside the container.
   • Verified permissions are 644 (rw-r--r--) and ownership is 1000:1000 (supabase:supabase).
   • cat inside container confirms valid HTML content.
2. Environment Variables:
   • Ran docker exec supabase-auth env and confirmed GOTRUE_MAILER_TEMPLATES_RECOVERY is set correctly to the file path.
3. Logs:
   • No "template not found" errors in docker logs supabase-auth.
   • Logs show "request completed" with status 200.
   • Warning: "Request received external host... NOT added to GOTRUE_MAILER_EXTERNAL_HOSTS".
4. A/B Testing (Critical Finding):
   • Changed GOTRUE_MAILER_TEMPLATES_RECOVERY to point to /etc/gotrue/templates/confirm_v2.html (a known working template for signup confirmation).
   • Result: The email sent for password recovery was still the index.html / empty body. It did NOT send the confirmation HTML.
   • Conclusion: The GOTRUE_MAILER_TEMPLATES_RECOVERY variable appears to be completely ignored or overridden by some internal logic, specifically for the Recovery flow.

Expected Behavior:
GoTrue should load the HTML file specified in GOTRUE_MAILER_TEMPLATES_RECOVERY and use it for the password reset email.

Actual Behavior:
GoTrue sends the application's root index.html (effectively a blank email in clients that require JS), ignoring the template file content entirely.

Workaround (Partial):
Setting GOTRUE_MAILER_TEMPLATES_RECOVERY="" (empty string) forces the default text email, which works correctly. However, custom HTML templates seem unusable for recovery in this version/setup.
Has anyone encountered this specific behavior where recovery templates are ignored despite valid configuration and file access?

(GoTrue v2.183.0 / v2.164.0)

[nissimlavy]

This smells less like a filesystem/env issue and more like the recovery flow bypassing the template loader entirely.

In GoTrue, recovery emails historically route through a different code path than signup confirmation, and in some versions the recovery handler hard-falls back to site URL rendering if ExternalURL or MailerURLPaths aren’t resolved cleanly.

Two things I’d check:

Whether GOTRUE_SITE_URL is being used as a hard fallback in recovery specifically

Whether the recovery mailer ignores file-backed templates unless GOTRUE_MAILER_URLPATHS_RECOVERY is explicitly set

The fact that pointing to a known-good confirm template still sends index.html is the key signal here.

[kopko13]

Thanks a lot for the detailed suggestion! It sounded very promising.

I tried explicitly setting GOTRUE_MAILER_URLPATHS_RECOVERY to /auth/v1/verify in my docker-compose.yml (and verified it was correctly present in the container environment), but unfortunately, the result is exactly the same: GoTrue still falls back to rendering the site URL (index.html) instead of loading the file-backed template.

It seems like the template loader is indeed being bypassed or failing silently regardless of the URL path configuration in this version/setup. I've reverted to the default text email for now. Thanks again for the help!"

[nissimlavy]

Thanks for testing and confirming.

Given that pointing GOTRUE_MAILER_TEMPLATES_RECOVERY at a known-working template still results in index.html, I agree this looks like the recovery flow bypassing the file template loader entirely in this version.

One quick way to confirm where it’s breaking:

• Temporarily set GOTRUE_MAILER_TEMPLATES_RECOVERY to a non-existent path and watch the auth logs during a recovery send.
  If there’s no change in logging or behavior, it would strongly suggest the recovery path never attempts to load file-backed templates at all.

At that point I’d suspect either:

• a regression specific to recovery in this GoTrue version, or
• recovery emails falling back to SITE_URL rendering when the external host/path validation fails (even silently).

If you do find a version where this works, pinning it may be the safest option for now.

[kopko13]

That was the smoking gun!

I followed your advice and set GOTRUE_MAILER_TEMPLATES_RECOVERY to a non-existent path (/etc/gotrue/templates/does_not_exist.html). The result: There were absolutely no errors in the logs (no "file not found" or similar warnings). The API simply returned 200 OK and proceeded to send the site's index.html as the email body, just like before.

This confirms your hypothesis: the recovery flow in this version is definitively bypassing the file template loader entirely, essentially treating the configuration as if it didn't exist.

I've reverted to the default text email (by setting the variable to an empty string) as a stable fallback. Thanks again for the diagnostic tip; at least now we know for sure it's a bug/limitation in the code path and not a config issue!"

[nissimlavy]

Perfect, that result closes the loop.

With a nonexistent template path producing identical behavior and zero loader errors, this pretty conclusively shows the recovery flow is skipping the file template loader altogether in these versions.

At this point it’s either:

• a regression introduced in the v2 recovery path, or
• an intentional divergence where recovery only supports text templates (but isn’t documented as such).

Your fallback to the default text email is the safest move for now. I’d recommend filing this as a bug with the repro steps you outlined -- the nonexistent-path test is the key detail that makes it actionable for maintainers.

Glad we could at least turn it into a known constraint instead of a mystery.

[aantti]

@singh-inder

[singh-inder]

@kopko13 Hi, This isn't a bug. Email template env vars such as GOTRUE_MAILER_TEMPLATES_RECOVERY have to be a url and this url should return a template. And it doesn't have to be public. You can simply add a static file-server container in your docker-compose.yml file

in the below example I am using a static file server in the same docker network as auth container. This is the static file server I am using https://github.com/halverneus/static-file-server This can be any file server you want. auth container simply needs a url which it can make a GET request to and this url should return a valid template.

services:
	auth:
		environment:
			GOTRUE_MAILER_TEMPLATES_RECOVERY: http://templates-server/reset_password.html
			
	templates-server:
		image: halverneus/static-file-server:v1.8.11
		environment:
			PORT: 80
		volumes:
			- ./volumes/auth_templates:/web

[kopko13]

Thanks a lot for your help!
I can confirm that this solution works perfectly on my side now.
Really appreciate the clear explanation and the quick support.

[aantti]

Also, https://supabase.com/docs/guides/self-hosting/custom-email-templates by @singh-inder :)