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 diving into specific problems, enable PgBeam's debug output. This adds a NOTICE to every query response with cache, routing, and timing information:

SET pgbeam.debug = on;
SELECT * FROM users LIMIT 1;
-- NOTICE: pgbeam: cache=hit age=12s ttl=60s 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 <project-id>.aws.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 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.aws.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: 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 authentication attempts

Too many failed authentication attempts from the same IP address in a short period.

Fix:

1. Stop the source of failed authentications (misconfigured client, wrong password in environment)
2. Wait a few minutes for the rate limit to expire
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 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.
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.
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.

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:

   /* @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 *.aws.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.

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 relay latency (30-150ms). Cache hits are served locally with sub-millisecond latency.

Mitigations:

• Enable caching for repeated reads to serve them from the local edge
• Add read replicas in regions closer to your application
• If latency is critical, consider deploying your database closer to your users

SQLSTATE quick reference

See Error Codes for the full reference 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 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 with the debug output, SQLSTATE, and steps to reproduce