--- 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-10-30T03:14:55.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: ```sql title="Enable debug output" SET pgbeam.debug = on; SELECT * FROM users LIMIT 1; -- NOTICE: pgbeam:cache hit age=12s ttl=1m0s swr=30s ``` 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:** 1. **Verify the hostname.** It should be `.proxy.pgbeam.app` on port `5432`. Check for typos. 2. **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. 3. **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. 4. **Confirm the project exists.** Log in to [dash.pgbeam.com](https://dash.pgbeam.com) and verify the project is there and the organization is active. 5. **Check PgBeam status.** Visit the PgBeam status page or run `pgbeam platform health` in the CLI. ### `08004`: Project not found ``` FATAL: project not found for hostname "xyz.proxy.pgbeam.app" ``` 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 ``` FATAL: connection rejected: IP address not in project allowlist ``` The project has an IP allowlist configured and your client's IP is not in it. **Checklist:** 1. **Check the allowlist.** Go to your project's **Settings > Security** to see which CIDR ranges are allowed. 2. **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. 3. **Add the IP.** Add your IP (as `/32` for a single address) or CIDR range to the allowlist. 4. **Check all environments.** Make sure CI/CD, staging, monitoring tools, and developer machines are all included. See [IP Allowlisting](/docs/ip-allowlist) for configuration details. ### `08004`: Organization suspended ``` FATAL: organization suspended; update payment at dash.pgbeam.com ``` 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 ``` FATAL: password authentication failed for user "myuser" ``` PgBeam forwarded your credentials to the origin database and it rejected them. This is an upstream issue, not a PgBeam issue. **Checklist:** 1. **Test direct connection.** Connect directly to the origin database with the same credentials. If it fails there too, the problem is not PgBeam. 2. **Check the database name.** Verify that the database name configured in PgBeam matches the actual database you want to connect to. 3. **Check user permissions.** Confirm the database user has `CONNECT` permission: `SELECT usename, usesuper FROM pg_user WHERE usename = 'myuser';` 4. **Check pg_hba.conf.** If the origin uses host-based authentication rules, ensure the PgBeam IP range is allowed. ### `08004`: Auth rate limited ``` FATAL: too many connection attempts from your IP; please retry with exponential backoff ``` Too many connection attempts from the same IP address in a short period. Loopback addresses are exempt. **Fix:** 1. Stop the source of failed authentications (misconfigured client, wrong password in environment) 2. Retry with exponential backoff rather than in a tight loop 3. Verify credentials are correct before retrying ## Upstream problems ### `08006`: Circuit breaker open ``` FATAL: upstream unavailable (circuit breaker open) ``` The origin database failed 3 consecutive connection attempts. PgBeam opened the circuit breaker to stop hammering it. **Checklist:** 1. **Check origin health.** Can you connect directly to the origin database from another client? 2. **Check connection limits.** Has the origin database hit its own `max_connections` limit? 3. **Check network path.** Are there firewall rules, security groups, or IP allowlists blocking PgBeam? 4. **Wait for recovery.** The circuit breaker probes automatically every 5-60 seconds (exponential backoff). Successful probes restore traffic. See [Resilience](/docs/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:** 1. Enable `pgbeam.debug` to confirm queries are reaching the upstream (you'll see `cache=miss`) 2. Run the same query directly against the origin to compare latency 3. Check the origin database for slow query logs, lock contention, or resource exhaustion ## Connection limit problems ### `53300`: Too many connections ``` FATAL: too many connections for project ``` The project hit its concurrent connection limit (20 / 100 / 500 depending on plan). **Fixes, in order of preference:** 1. **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](/docs/pooling). 2. **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. 3. **Close idle connections.** Check for dev tools, monitoring scripts, or migration runners holding connections open. 4. **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 ``` FATAL: query rate limit exceeded ``` The project exceeded its QPS limit (10 / 50 / 250 depending on plan). **Fixes:** 1. **Enable caching** for high-frequency repeated reads. Cached queries reduce upstream load and the effective QPS. See [Caching](/docs/cache). 2. **Batch queries** where possible. Multiple small queries can sometimes be combined. 3. **Check for runaway clients.** A misconfigured cron job or retry loop can exhaust the QPS budget. 4. **Upgrade your plan** for a higher QPS allowance. ## Agent problems Agent credentials get errors of their own, each with a stable message prefix. [Error Codes](/docs/error-codes) lists every message and the policy control behind it. ### `42501`: Blocked by agent policy The policy refused the statement. The message after `blocked by PgBeam agent policy: ` names the rule; check it with `pgbeam policies dry-eval` before changing the policy. See [Blocked by policy](/docs/error-codes#42501-blocked-by-policy). ### `0A000`: Statement shape not supported Approvals, row filters, masking, affected-row caps and dry-run writes need the simple query protocol for some statements, and most drivers default to prepared statements. Switch the driver to simple-protocol mode for agent credentials. See [Not supported](/docs/error-codes#0a000-not-supported). ### `28000`: Agent session terminated The credential was revoked, disabled, expired or rotated, or the project kill-switch was engaged, while the session was open. Reconnect with a valid credential. See [Agent session terminated](/docs/error-codes#28000-agent-session-terminated). ### `53400`: Agent budget exhausted The credential spent its query or egress budget, or an approval timed out. The message gives the reset time. See [Agent budget or approval limit](/docs/error-codes#53400-agent-budget-or-approval-limit). ## Cache problems ### Cache is not caching anything **Checklist:** 1. **Is caching enabled?** Caching is off by default. Check that it is enabled via cache rules, session override, or database default. 2. **Is the query a read?** Only `SELECT` statements are cacheable. 3. **Is the query inside a transaction?** Queries in `BEGIN`/`COMMIT` blocks are never cached. 4. **Does the query use volatile functions?** `NOW()`, `RANDOM()`, `pg_advisory_lock()`, and similar functions cause bypass. 5. **Does the SQL explicitly disable cache?** Check for `/* @pgbeam:cache noCache */`. 6. **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:** 1. **Use `noCache` for read-after-write queries:** ```sql /* @pgbeam:cache noCache */ SELECT * FROM orders WHERE id = 123; ``` 2. **Reduce TTL** for query shapes where freshness is important. 3. **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:** 1. **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. 2. **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. 3. **Custom domains:** If using a custom domain, verify the ACME challenge CNAME is in place so PgBeam can provision the certificate. See [Custom Domains](/docs/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](/docs/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-project-not-found) | | `08004` | IP not allowed | [Connection problems](#08004-ip-not-allowed) | | `08004` | Organization suspended | [Connection problems](#08004-organization-suspended) | | `08004` | Auth rate limited | [Authentication problems](#08004-auth-rate-limited) | | `08006` | Upstream auth failure | [Authentication problems](#08006-authentication-failed) | | `08006` | Circuit breaker open | [Upstream problems](#08006-circuit-breaker-open) | | `53300` | Too many connections | [Connection limit problems](#53300-too-many-connections) | | `53400` | Query rate limit exceeded | [Rate limit problems](#53400-query-rate-limit-exceeded) | | `42501` | Blocked by agent policy | [Agent problems](#42501-blocked-by-agent-policy) | | `0A000` | Statement shape not supported for an agent | [Agent problems](#0a000-statement-shape-not-supported) | | `28000` | Agent session terminated | [Agent problems](#28000-agent-session-terminated) | | `53400` | Agent budget exhausted | [Agent problems](#53400-agent-budget-exhausted) | See [Error Codes](/docs/error-codes) for every SQLSTATE PgBeam returns, with code examples. ## Still stuck? If you have worked through the relevant section and the problem persists: 1. Enable `pgbeam.debug` and capture the NOTICE output 2. Check [Error Codes](/docs/error-codes) for the specific SQLSTATE 3. Test a direct connection to the origin database to isolate PgBeam vs upstream 4. Contact support at [support@pgbeam.com](mailto:support@pgbeam.com) with the debug output, SQLSTATE, and steps to reproduce