Categories of PostgreSQL Issues &
Diagnostic Tips
1️⃣ Connection Issues
Symptoms: Cannot connect, authentication failures, timeouts
Common causes:
Incorrect pg_hba.conf or postgresql.conf settings
Firewall or SELinux blocking ports
Max connections exceeded
Diagnostics:
Check PostgreSQL logs (pg_log/) for authentication errors
Use psql locally and remotely to test connections
Check max_connections with:
SHOW max_connections;
Inspect firewall rules (firewall-cmd --list-all or iptables -L)
2️⃣ Performance Problems
Symptoms: Slow queries, high CPU, IO waits, lock contention
Common causes:
Missing indexes or bad query plans
Autovacuum not keeping up → bloat
Inefficient configuration (work_mem, shared_buffers)
Long-running transactions holding locks
Diagnostics:
Check pg_stat_activity for long queries:
SELECT pid, state, query_start, query FROM pg_stat_activity WHERE state
= 'active' ORDER BY query_start;
Use EXPLAIN ANALYZE on slow queries
Monitor autovacuum status:
SELECT * FROM pg_stat_user_tables WHERE n_dead_tup > 1000;
Review logs for slow queries and deadlocks
3️⃣ Replication & High Availability Issues
Symptoms: Standby lag, replication slots bloated, failover problems
Common causes:
Network latency or firewall issues
Replication slots preventing WAL cleanup
Incorrect primary_conninfo or pg_hba.conf permissions
Synchronous replication configuration issues
Diagnostics:
On primary:
SELECT * FROM pg_stat_replication;
Check WAL archive folder size and replication slot status:
SELECT * FROM pg_replication_slots;
Review postgresql.conf for wal_level, max_wal_senders
📄 Page 2: More Issues & General
Troubleshooting Tips
4️⃣ Disk Space & File System Issues
Symptoms: Database crashes, cannot write to disk, slow IO
Common causes:
Disk full or near capacity
Permission problems on data directory or WAL archive
Filesystem not tuned for database workload (e.g. no async I/O)
Diagnostics:
Check disk usage:
df -h
Check PostgreSQL data directory permissions
Check dmesg for disk errors or IO issues
5️⃣ Locking & Deadlocks
Symptoms: Queries blocked, application timeouts
Common causes:
Long-running transactions holding locks
Unindexed foreign keys causing lock waits
Deadlocks from cyclic lock dependencies
Diagnostics:
Check blocked queries:
SELECT blocked_locks.pid AS blocked_pid, blocking_locks.pid AS
blocking_pid, blocked_activity.query AS blocked_query,
blocking_activity.query AS blocking_query
FROM pg_locks blocked_locks
JOIN pg_stat_activity blocked_activity ON blocked_activity.pid =
blocked_locks.pid
JOIN pg_locks blocking_locks ON blocking_locks.locktype =
blocked_locks.locktype AND blocking_locks.database IS NOT DISTINCT FROM
blocked_locks.database AND blocking_locks.relation IS NOT DISTINCT FROM
blocked_locks.relation AND blocking_locks.page IS NOT DISTINCT FROM
blocked_locks.page AND blocking_locks.tuple IS NOT DISTINCT FROM
blocked_locks.tuple AND blocking_locks.virtualxid IS NOT DISTINCT FROM
blocked_locks.virtualxid AND blocking_locks.transactionid IS NOT
DISTINCT FROM blocked_locks.transactionid AND blocking_locks.pid !=
blocked_locks.pid
JOIN pg_stat_activity blocking_activity ON blocking_activity.pid =
blocking_locks.pid
WHERE NOT blocked_locks.granted;
Look for deadlock logs in PostgreSQL logs (log_lock_waits, log_deadlocks enabled)
6️⃣ Configuration Issues
Symptoms: Unexpected crashes, poor performance, startup failures
Common causes:
Misconfigured memory settings causing OOM kills
Conflicting parameters (max_worker_processes, max_parallel_workers)
Incorrect file permissions on config files
Diagnostics:
Check PostgreSQL logs for config errors at startup
Review current settings:
SHOW all;
Validate config syntax with:
pg_ctl reload
General Troubleshooting Tips
Always check PostgreSQL logs (/var/lib/pgsql/16/data/pg_log/) first
Use pg_stat_activity and pg_stat_replication to monitor real-time status
Enable extended logging temporarily for deeper analysis
Use tools like pgBadger for log analysis, pg_top for live stats
Keep PostgreSQL updated with latest minor versions for bug fixes
