Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

[bot] Sync from supabase/troubleshooting (#45679)

supabase-supabase-autofixer[bot]f8e19e687878
diff --git a/apps/docs/content/troubleshooting/auth-error-503-authretryablefetcherror-51b88c.mdx b/apps/docs/content/troubleshooting/auth-error-503-authretryablefetcherror-51b88c.mdx
new file mode 100644
index 00000000000..5108fa277c4
--- /dev/null
+++ b/apps/docs/content/troubleshooting/auth-error-503-authretryablefetcherror-51b88c.mdx
@@ -0,0 +1,29 @@
+---
+title = "Auth error: 503 AuthRetryableFetchError"
+date_created = "2026-05-07T09:19:37+00:00"
+topics = [ "auth" ]
+keywords = []
+[[errors]]
+http_status_code = 503
+message = "AuthRetryableFetchError"
+
+---
+
+A `503` status code accompanied by an `AuthRetryableFetchError` typically indicates that the Auth (GoTrue) service is failing to initialize because it cannot load its configuration.
+
+**Why Does This Happen?**
+This issue is most commonly caused by an invalid duration string in the `GOTRUE_SESSIONS_TIMEBOX` setting. This occurs if the configured value:
+
+- Exceeds the maximum supported duration (approximately hundreds of years).
+- Uses an incorrect or unsupported time unit format.
+
+When the service encounters an invalid configuration value during startup, it fails to initialize, resulting in fetch errors for all authentication requests.
+
+**How to Resolve:**
+
+1. Navigate to the [Sessions](/dashboard/project/_/auth/sessions) settings in the dashboard.
+2. Locate the **Timebox** duration field within the **User Sessions** section.
+3. Replace the current value with a smaller, valid duration or fallback to the default value (`4320` hours).
+4. Save your changes.
+
+Updating this field triggers a configuration reload, which allows the Auth service to restart and resume normal operation.
diff --git a/apps/docs/content/troubleshooting/supavisor-error-circuit-breaker-open-after-password-rotation-0fdb72.mdx b/apps/docs/content/troubleshooting/supavisor-error-circuit-breaker-open-after-password-rotation-0fdb72.mdx
new file mode 100644
index 00000000000..8516e7917db
--- /dev/null
+++ b/apps/docs/content/troubleshooting/supavisor-error-circuit-breaker-open-after-password-rotation-0fdb72.mdx
@@ -0,0 +1,31 @@
+---
+title = "Supavisor error: 'Circuit breaker open' after password rotation"
+date_created = "2026-05-07T09:17:40+00:00"
+topics = [ "database", "supavisor" ]
+keywords = []
+---
+
+If you are seeing `FATAL: Circuit breaker open` with one of the error messages:
+
+- `failed to retrieve database credentials after multiple attempts, new connections are temporarily blocked`
+- `too many failed attempts to connect to the database, new connections are temporarily blocked`
+- `too many authentication failures, new connections are temporarily blocked`
+
+it indicates that the connection pooler has blocked the origin IP to protect the database.
+
+This typically happens when clients attempt to connect to the pooler (ports 5432 or 6543) using an outdated password after a rotation.
+
+**Why Does This Happen?**
+
+- To prevent overloading the database with failed authentication attempts, Supavisor triggers a circuit breaker.
+- Once triggered, the origin IP is blocked for up to 2 minutes.
+- If clients continue attempting connections with invalid credentials during this window, the circuit breaker will reapply, effectively extending the lockout.
+
+**How to Resolve This Issue:**
+
+- **Stop clients:** Shut down application instances or services currently attempting to connect to the pooler with the wrong credentials.
+- **Update credentials:** Ensure all connection strings and environment variables are updated with the new database password.
+- **Restart services:** Resume application traffic and the clients will be able to reconnect after the lockout period has elapsed.
+
+**Prevention:**
+To avoid this IP lockout issue in the future, stop application instances before rotating the database password. Only restart your services once the new credentials have been successfully applied to your configuration.