--- title: "Troubleshooting" description: "Common PgBeam failures, what they usually mean, and step-by-step instructions to diagnose and fix them." canonical: "https://pgbeam.com/docs/troubleshooting" last-updated: "2026-09-14T19:37:21.000Z" --- # Troubleshooting > Common PgBeam failures, what they usually mean, and step-by-step instructions to diagnose and fix them. URL: https://pgbeam.com/docs/troubleshooting Something is broken, traffic is failing, and you need to figure out whether the problem is in PgBeam, your origin database, or your application configuration. This guide walks through the most common issues. ## Start with debug mode Before tackling specific problems, enable PgBeam's debug output. This adds a `NOTICE` to every query response with cache, routing, and timing information: Debug notices tell you: Whether the query was a cache **hit**, **miss**, **stale hit**, or **bypass** Cache timing: how old the cached entry is, TTL, and SWR values Whether **replica routing** was used and which upstream handled the query Disable it again with `SET pgbeam.debug = off`. ## Connection problems ## Cannot connect at all **Symptoms:** Connection timeout, connection refused, or DNS resolution failure. **Checklist:** **Verify the hostname.** It should be `.proxy.pgbeam.app` on port `5432`. Check for typos. **Verify TLS is enabled.** PgBeam requires TLS. Most PostgreSQL drivers enable it by default, but check your connection string for `sslmode=disable`. That will not work. **Check your firewall.** Confirm outbound TCP traffic on port 5432 is allowed from your environment. Corporate networks, VPNs, and cloud security groups sometimes block non-HTTP ports. **Confirm the project exists.** Log in to dash.pgbeam.com and verify the project is there and the organization is active. **Check PgBeam status.** Visit the PgBeam status page or run `pgbeam platform health` in the CLI. ## `08004`: Project not found The hostname does not match any project. Common causes: Typo in the connection string The project was deleted Using a custom domain that hasn't been verified yet **Fix:** Check the hostname in your `DATABASE_URL` against the project hostname in the dashboard. ## `08004`: IP not allowed The project has an IP allowlist configured and your client's IP is not in it. **Checklist:** **Check the allowlist.** Go to your project's **Settings > Security** to see which CIDR ranges are allowed. **Find your egress IP.** Your client's outbound IP may differ from what you expect: cloud platforms, VPNs, and NAT gateways change the source IP. Run `curl ifconfig.me` from the environment that connects to PgBeam. **Add the IP.** Add your IP (as `/32` for a single address) or CIDR range to the allowlist. **Check all environments.** Make sure CI/CD, staging, monitoring tools, and developer machines are all included. See IP Allowlisting for configuration details. ## `08004`: Organization suspended The organization's billing is inactive. This happens when: A payment method fails The trial expired without a payment method An owner cancelled the subscription **Fix:** Go to **Settings > Billing** in the dashboard and update the payment method or reactivate. ## Authentication problems ## `08006`: Authentication failed PgBeam forwarded your credentials to the origin database and it rejected them. This is an upstream issue, not a PgBeam issue. **Checklist:** **Test direct connection.** Connect directly to the origin database with the same credentials. If it fails there too, the problem is not PgBeam. **Check the database name.** Verify that the database name configured in PgBeam matches the actual database you want to connect to. **Check user permissions.** Confirm the database user has `CONNECT` permission: `SELECT usename, usesuper FROM pg_user WHERE usename = 'myuser';` **Check pg\_hba.conf.** If the origin uses host-based authentication rules, ensure the PgBeam IP range is allowed. ## `08004`: Auth rate limited Too many failed authentication attempts from the same IP address in a short period. **Fix:** Stop the source of failed authentications (misconfigured client, wrong password in environment) Wait a few minutes for the rate limit to expire Verify credentials are correct before retrying ## Upstream problems ## `08006`: Circuit breaker open The origin database failed 3 consecutive connection attempts. PgBeam opened the circuit breaker to stop hammering it. **Checklist:** **Check origin health.** Can you connect directly to the origin database from another client? **Check connection limits.** Has the origin database hit its own `max_connections` limit? **Check network path.** Are there firewall rules, security groups, or IP allowlists blocking PgBeam? **Wait for recovery.** The circuit breaker probes automatically every 5-60 seconds (exponential backoff). Successful probes restore traffic. See Resilience for details on circuit breaker states and recovery. ## Origin database is slow If queries are slow but connections work, PgBeam is passing traffic through correctly. The issue is upstream. **Checklist:** Enable `pgbeam.debug` to confirm queries are reaching the upstream (you'll see `cache=miss`) Run the same query directly against the origin to compare latency Check the origin database for slow query logs, lock contention, or resource exhaustion ## Connection limit problems ## `53300`: Too many connections The project hit its concurrent connection limit (20 / 100 / 500 depending on plan). **Fixes, in order of preference:** **Reduce client pool size.** If you have 4 app servers each with a pool of 20, that's 80 connections. With PgBeam, use 3-5 per instance instead. See Connection Pooling. **Switch to transaction pool mode.** Session mode (the default) holds an upstream connection for the entire client session. Transaction mode releases it after each transaction, dramatically improving reuse. **Close idle connections.** Check for dev tools, monitoring scripts, or migration runners holding connections open. **Upgrade your plan.** If the workload has genuinely outgrown the current tier. ## Connections spike after deploy After a rolling deploy, old and new instances briefly overlap, doubling the connection count. This is normal and resolves as old instances shut down. **Mitigation:** Set short connection pool idle timeouts in your application Use transaction pool mode to reduce the per-instance connection footprint If the spike exceeds your limit, consider upgrading temporarily or staggering deploys ## Rate limit problems ## `53400`: Query rate limit exceeded The project exceeded its QPS limit (10 / 50 / 250 depending on plan). **Fixes:** **Enable caching** for high-frequency repeated reads. Cached queries reduce upstream load and the effective QPS. See Caching. **Batch queries** where possible. Multiple small queries can sometimes be combined. **Check for runaway clients.** A misconfigured cron job or retry loop can exhaust the QPS budget. **Upgrade your plan** for a higher QPS allowance. ## Cache problems ## Cache is not caching anything **Checklist:** **Is caching enabled?** Caching is off by default. Check that it is enabled via cache rules, session override, or database default. **Is the query a read?** Only `SELECT` statements are cacheable. **Is the query inside a transaction?** Queries in `BEGIN`/`COMMIT` blocks are never cached. **Does the query use volatile functions?** `NOW()`, `RANDOM()`, `pg_advisory_lock()`, and similar functions cause bypass. **Does the SQL explicitly disable cache?** Check for `/* @pgbeam:cache noCache */`. **Enable debug mode** and check the NOTICE output to see why the query is not being cached. ## Getting stale data after writes If you write data and immediately read it back, you may get a cached (stale) version of the old data. **Fixes:** **Use `noCache` for read-after-write queries:** **Reduce TTL** for query shapes where freshness is important. **Disable caching** for queries that must always return the latest data. ## Cache hit rate is low A low cache hit rate means the cache is not saving much upstream load. **Common causes:** Queries have highly variable parameters (each unique set of params creates a new cache entry) TTL is too short for the query frequency The workload is write-heavy and data changes between reads ## TLS problems ## Client rejects the certificate **Checklist:** **Update your CA bundle.** PgBeam uses publicly trusted certificates that work with all modern systems. If your client is running on an old OS or container image, the CA bundle may be outdated. **Check the hostname.** The certificate matches `*.proxy.pgbeam.app`. If you are using an IP address or a hostname that does not match, TLS validation will fail. **Custom domains:** If using a custom domain, verify the ACME challenge CNAME is in place so PgBeam can provision the certificate. See Custom Domains. ## TLS required but client is not using it PgBeam requires TLS for all connections. If your client has TLS disabled (`sslmode=disable`), the connection will fail. **Fix:** Remove `sslmode=disable` from your connection string or set `sslmode=require`. ## Performance problems ## First connection after inactivity is slow Projects with no activity for 5 minutes enter a **parked** state. The first connection triggers a cold start that adds some latency. Subsequent connections are fast. This is expected behavior. See Resilience for details on scale-to-zero. ## Cross-region latency If your database is in one region but your application is in another, cache misses incur cross-region latency (30-150ms). Cache hits are served locally with sub-millisecond latency. **Mitigations:** Enable caching for repeated reads to serve them from the nearest region Add read replicas in regions closer to your application If latency is critical, consider deploying your database closer to your users ## SQLSTATE quick reference SQLSTATE Message Section `08004` Project not found Connection problems `08004` IP not allowed Connection problems `08004` Organization suspended Connection problems `08004` Auth rate limited Authentication problems `08006` Upstream auth failure Authentication problems `08006` Circuit breaker open Upstream problems `53300` Too many connections Connection limit problems `53400` Query rate limit exceeded Rate limit problems See Error Codes for the full reference with code examples. ## Still stuck? If you have worked through the relevant section and the problem persists: Enable `pgbeam.debug` and capture the NOTICE output Check Error Codes for the specific SQLSTATE Test a direct connection to the origin database to isolate PgBeam vs upstream Contact support at support\@pgbeam.com with the debug output, SQLSTATE, and steps to reproduce