Skip to main content
View rawEdit

Troubleshooting

Common errors and how to fix them.

Checkup errors​

pg_stat_statements not enabled​

Symptom: Checkup warns that pg_stat_statements is not available. Query-level checks (K-series) are skipped.

Fix:

-- Enable the extension
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Then restart PostgreSQL. The extension requires shared_preload_libraries to include pg_stat_statements:

# postgresql.conf
shared_preload_libraries = 'pg_stat_statements'

Permission denied​

Symptom: Checkup fails with permission errors when querying system catalogs.

Fix: Create a monitoring user with the pg_monitor role:

CREATE USER postgres_ai_mon PASSWORD '****';
GRANT pg_monitor TO postgres_ai_mon;

Or use the CLI helper:

npx postgresai prepare-db postgresql://admin:password@host:5432/dbname

SSL negotiation failed​

Symptom: Connection fails with SSL-related errors.

Fix: Add SSL mode to your connection string:

npx postgresai checkup "postgresql://user:pass@host:5432/dbname?sslmode=require"

For self-signed certificates:

npx postgresai checkup "postgresql://user:pass@host:5432/dbname?sslmode=require&sslrootcert=/path/to/ca.pem"

Connection refused​

Symptom: Cannot connect to the database.

Fix: Check that:

  1. PostgreSQL is running and accepting connections
  2. pg_hba.conf allows connections from your IP
  3. The port is correct (default: 5432)
  4. Any firewall or security group allows the connection

Monitoring stack errors​

Grafana not loading​

Symptom: http://localhost:3000 is unreachable after local-install.

Fix:

# Check service status
npx postgresai mon status

# Check logs for errors
npx postgresai mon logs

# Restart the stack
npx postgresai mon stop
npx postgresai mon start

If Docker containers are not starting, verify Docker is running:

docker ps

Metrics not appearing in dashboards​

Symptom: Dashboards show "No data" for all panels.

Fix:

  1. Check that the monitored database is reachable from the monitoring stack:

    npx postgresai mon health

  2. Verify the data source in Grafana (Settings > Data Sources > VictoriaMetrics/Prometheus)

  3. Wait for collection — some metrics take up to 5 minutes to appear after initial setup. Bloat metrics are collected every 2-3 hours.

  4. Check pgwatch logs for connection errors:

    npx postgresai mon logs pgwatch

Docker Compose version conflicts​

Symptom: docker compose commands fail with syntax errors.

Fix: Ensure you have Docker Compose V2:

docker compose version
# Should show v2.x or later

If you have the old docker-compose (V1), upgrade Docker Desktop or install the Compose plugin.

Port conflicts​

Symptom: local-install fails because port 3000 is already in use.

Fix: Stop the conflicting service, or check if a previous monitoring stack is still running:

npx postgresai mon stop
npx postgresai mon local-install

Upgrade issues​

Dashboards missing after upgrade​

Symptom: After upgrading, some dashboards are missing or show old versions.

Fix: Re-run local-install to pull new dashboard definitions:

npx postgresai mon stop
npx postgresai mon local-install -y

See Upgrading for the full upgrade procedure.

Getting help​

If your issue is not listed here: