Troubleshooting

Agent Issues

Database doesn't appear in the dashboard

1. Check agent logs for connection errors
2. Verify the API key is correct and not revoked
3. Confirm the DSN is reachable from the agent's network
4. Check that the monitoring user has the required permissions — see PostgreSQL Setup or ClickHouse Setup

"no config file found"

Set the BASIRA_CONFIG environment variable to point to your config file, or place config.yaml in the agent's working directory.

"connection refused" or timeout

The agent can't reach the database. Check:

• DSN host and port are correct
• Firewall or security group allows the connection
• The database is running and accepting connections

Agent keeps reconnecting

The agent reconnects after 3 consecutive health check failures (pinged every 10s). Check:

• Database isn't overloaded or out of connections
• Network stability between agent and database
• max_connections on the database isn't exhausted

Buffer files appearing

Files named basira_buffer_{name}.db appear when the agent can't reach the Basira API. Buffered data is retried every 30 seconds and kept for up to 1 hour. The files are cleaned up automatically once the API is reachable again.

Agent not collecting all metrics

Some collectors require specific PostgreSQL versions:

• pg_stat_wal requires PostgreSQL 14+
• pg_stat_io requires PostgreSQL 16+

These collectors are silently skipped on older versions.

If you've set enabled_collectors in your config, only those collectors will run. Remove the field to enable all collectors.

Dashboard Issues

Metrics show "no data"

• The agent may not have pushed telemetry yet (wait 30 seconds after agent start)
• Check the database health status — a disconnected database won't have current data
• Verify the time range picker isn't set to a period before the agent was deployed

Stale data / metrics not updating

• Check that the agent is running: kubectl logs deployment/basira-agent --tail=20
• Use the agent health endpoint: curl http://<agent>:8081/healthz
• Look for push errors in agent logs

Inconsistent or jumpy query stats

If pg_stat_statements counters appear to reset between polls, or active queries seem to flip between unrelated sessions, you may be connecting through a cluster or load-balancer endpoint that routes to different physical instances. The agent needs a stable connection to a single node. Switch to a direct instance endpoint — see Agent Configuration.

"Unverified account" limitations

Unverified accounts are limited to:

• 1 database
• 24 hours of data retention

Verify your email to remove these limits. Check your inbox (and spam folder) for the verification email, or resend it from the dashboard.

API Issues

401 Unauthorized

• API key may be revoked — generate a new one from Settings > API Keys
• JWT token may be expired — refresh it or log in again
• Verify you're using the correct header: X-API-Key or Authorization: Bearer

429 Too Many Requests

Authentication endpoints are rate-limited:

Wait for the rate limit window to reset, or use API key authentication for data endpoints (which are not rate-limited).

403 Forbidden

Your organization may need email verification to access advanced features. Check your verification status at Settings or via GET /api/v1/auth/me.

PostgreSQL-Specific

pg_stat_statements is empty

• Verify the extension is loaded: SHOW shared_preload_libraries should include pg_stat_statements
• Restart PostgreSQL after adding it to shared_preload_libraries
• Run CREATE EXTENSION IF NOT EXISTS pg_stat_statements on the target database

No EXPLAIN plans appearing

EXPLAIN plans require either:

• The explain_plans collector (enabled by default) for sampled plans
• The auto_explain PostgreSQL extension with pg_log_dir configured for log-derived plans

Check that collect_explain_plans is enabled on the database instance.

ClickHouse-Specific

system.query_log is empty

• Verify log_queries = 1 in your user profile
• Check query_log configuration in config.xml
• Wait for the flush interval (default 7500ms) after running queries

Agent can't connect

• The agent uses the ClickHouse native protocol (default port 9000), not HTTP (8123)
• For TLS: use ?secure=true in the DSN
• Both clickhouse:// and tcp:// DSN prefixes are supported