Troubleshooting

PostgreSQL Issues

Connection refused

Symptoms: could not connect to server: Connection refused

Causes and solutions:

1. Instance not active — Check your instance status in the dashboard. If it shows "Provisioning", wait for it to complete.
2. Wrong host or port — Verify the connection details from the Settings tab. PostgreSQL uses port 5432.
3. Missing TLS — All connections require TLS. Add sslmode=require to your connection string.

# Test connectivity
psql 'postgresql://<username>:<password>@<host>:5432/<database>?sslmode=require'

Authentication failed

Symptoms: FATAL: password authentication failed for user

Solutions:

1. Double-check your username and password from the Settings tab
2. Ensure you're connecting to the correct database name
3. If connecting to a branch, use the branch's own credentials (not the main branch's)

Too many connections

Symptoms: FATAL: too many clients already

Solutions:

1. Check your current connections:

   SELECT count(*) FROM pg_stat_activity;

2. Identify idle connections:

   SELECT pid, usename, application_name, state, query_start
   FROM pg_stat_activity
   WHERE state = 'idle'
   ORDER BY query_start;

3. Terminate idle connections if needed:

   SELECT pg_terminate_backend(pid)
   FROM pg_stat_activity
   WHERE state = 'idle'
   AND query_start < NOW() - INTERVAL '1 hour';

4. Consider using a connection pooler like PgBouncer in your application

5. Upgrade your tier for higher max_connections

Slow queries

Symptoms: Queries taking longer than expected

Diagnosis steps:

1. Enable query tracking:

   CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

2. Find the slowest queries:

   SELECT query, calls,
     round(mean_exec_time::numeric, 2) AS avg_ms,
     round(total_exec_time::numeric, 2) AS total_ms
   FROM pg_stat_statements
   ORDER BY mean_exec_time DESC
   LIMIT 10;

3. Analyze a specific query:

   EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 42;

4. Check for missing indexes:

   SELECT relname, seq_scan, idx_scan
   FROM pg_stat_user_tables
   WHERE seq_scan > 100 AND idx_scan < seq_scan
   ORDER BY seq_scan DESC;

Solutions:

• Add indexes on columns used in WHERE, JOIN, and ORDER BY clauses
• Use LIMIT to avoid fetching unnecessary rows
• Avoid SELECT * — query only the columns you need
• Run VACUUM ANALYZE to update table statistics
• Upgrade your tier if resource limits are the bottleneck

Disk space running low

Symptoms: Dashboard shows high disk usage, or queries fail with could not write to file

Solutions:

1. Check what's using space:

   SELECT tablename,
     pg_size_pretty(pg_total_relation_size(schemaname || '.' || tablename)) AS total
   FROM pg_tables
   WHERE schemaname = 'public'
   ORDER BY pg_total_relation_size(schemaname || '.' || tablename) DESC;

2. Clean up dead tuples:

   VACUUM FULL;

3. Remove unnecessary data or old rows

4. Storage auto-scales if you have auto-scaling enabled. If not, upgrade your tier for more storage.

Extensions not working after restore

Symptoms: Errors referencing missing functions or types after restoring from a backup

Solution: PostgreSQL extensions may need to be reinstalled on restored branches:

-- Reinstall your extensions
CREATE EXTENSION IF NOT EXISTS pgcrypto;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-- Add your other extensions

Valkey Issues

Connection refused

Symptoms: Could not connect to Redis

Solutions:

1. Verify host and port from the Settings tab (Valkey uses port 6379)
2. Ensure you're using TLS — use rediss:// (double s) in connection URIs or --tls flag
3. Check that your instance is in Active status

# Test connectivity
valkey-cli -h <host> -p 6379 -a <password> --tls PING

NOAUTH / Authentication error

Symptoms: NOAUTH Authentication required or ERR invalid password

Solutions:

1. Verify your password from the Settings tab
2. Ensure the password is passed correctly:

   # CLI
   valkey-cli -h <host> -p 6379 -a <password> --tls
   
   # Connection URI
   rediss://<password>@<host>:6379

OOM (Out of Memory)

Symptoms: OOM command not allowed when used memory > maxmemory

Solutions:

1. Check memory usage:

   valkey-cli -h <host> -p 6379 -a <password> --tls INFO memory

2. Set TTLs on keys that don't need to persist indefinitely:

   EXPIRE mykey 3600

3. Remove unnecessary keys:

   DEL unused_key_1 unused_key_2

4. Review large keys:

   valkey-cli -h <host> -p 6379 -a <password> --tls --bigkeys

5. Upgrade your tier for more RAM

High latency

Symptoms: Commands taking longer than expected (> 1ms)

Diagnosis:

# Check slow log
valkey-cli -h <host> -p 6379 -a <password> --tls SLOWLOG GET 10

Solutions:

• Avoid KEYS * in production — use SCAN instead
• Use pipelining to batch multiple commands
• Check if your client library is reconnecting frequently (connection churn)
• Ensure your application is in the same or nearby region as your instance

General Issues

Instance stuck in "Provisioning"

If your instance has been in "Provisioning" status for more than 5 minutes:

1. Wait a few more minutes — peak times may cause slight delays
2. If the issue persists, contact support with your instance ID

Backup failed

If a backup shows "Failed" status:

1. Check if your instance was under heavy load during the backup
2. Verify your instance has enough storage for the backup process
3. Manually trigger a new backup from the Backups tab
4. If backups consistently fail, contact support

Cannot delete instance

1. Ensure you're deleting the correct instance (not the main branch)
2. The main branch cannot be deleted — delete the instance itself
3. If the delete button is disabled, the instance may be processing another operation. Wait and try again.

Getting Help

If your issue isn't covered here:

• Email us at [email protected]
• Include your instance ID and any error messages
• We typically respond within a few hours

Next Steps

• Monitoring — Track metrics to prevent issues
• Scaling — Upgrade resources if needed
• FAQ — Common questions