Troubleshooting Common Issues

Most of the issues people hit are network, permissions, or the same five extension gotchas. Here's the short list. Provider-specific quirks live on the dedicated RDS, Azure, Cloud SQL, and self-hosted pages.

"Disconnected" in the server header

Means no successful collection cycle in the last five minutes. Three things to check, in order:

First, your firewall or security group still allows MonPG's egress range on the DB port. The address is 20.107.185.112/29. People who add this once and forget it sometimes see Disconnected weeks later because their security tooling auto-reverts unrecognized rules. Re-check.

Second, the monitor role's password hasn't rotated. psql -h your-host -U monpg_monitor_<hex> -d postgres should connect. If it doesn't, MonPG can't either. (We used a randomly generated password during onboarding, stored ciphertext-only on our side. If you've rotated it externally, paste the new one in Settings → Servers.)

Third, check whether your provider has done a recent maintenance event. Some clouds reboot instances when patching, and if the reboot lasted long enough that we marked the server stale, it stays Disconnected until two consecutive successful cycles flip it back. This usually self-resolves within ten minutes; if not, click "Test connection" in Settings → Servers to force a probe.

"Failed to load data" on a page

The API couldn't read from the analytical store. Usually transient — click Try again. If it persists, check whether other pages also fail. If yes, the API's having a bad time and our status page (status.monpg.app) probably reflects it. If only one page fails, the most common cause is that pg_stat_statements_reset() ran on your DB recently and the collector is rebuilding its delta baseline. Data reappears after two or three cycles.

Tables / Indexes pages show no bloat data

You don't have pgstattuple installed. Bloat columns require it. Either tick the box on pgstattuple setup or live with the heuristic estimates from pg_stats. The basic table sizes still work without it.

Query Advisor stays empty

auto_explain isn't loaded. See auto_explain setup. Even with auto_explain loaded, if your log_min_duration is high (5000ms+) and your workload doesn't have anything slow enough, no plans get captured. That's not a bug — Query Advisor has nothing to advise. Lower the threshold.

Queries I see in pg_stat_statements aren't in MonPG

Three flavors of this:

If pg_stat_statements.track = top and the queries are nested (called from inside a function or trigger), they're filtered. Set track = all, or use auto_explain.log_nested_statements.

If pg_stat_statements.max = 5000 and your workload has more than 5000 distinct queries, the long tail evicts. Raise to 10000 (this requires a restart — postmaster context).

If track_activity_query_size = 1024, queries longer than ~1KB get truncated. Raise to 4096. Also a postmaster GUC.

Alert rule fires constantly, never resolves

Open Alerts → Rules → click the rule → check duration_secs. If it's 0, the rule fires the moment the threshold is exceeded, even for transient blips. Set it to 300 to require five sustained minutes. Most flapping rules calm down with this single change.

I added a database but it doesn't appear

Settings → Servers → your server → Databases tab. Your plan caps the number of monitored databases, so newly-discovered DBs need to be ticked manually if you're at the cap. If it's already ticked but data is missing, the collector might still be in its first per-DB fan-out cycle. Wait sixty seconds.

Agent container keeps restarting

Almost always one of:

invalid agent token — the token was revoked, or has expired (if you set an expiry), or you've copied it wrong. Generate a new one in Settings → Agent Tokens.

connection refused — your DB host is wrong, or the agent's host can't reach the DB on the configured port. If the agent is in a Docker container and you used localhost as the DB host, that means "the container itself," not your host machine. Use host.docker.internal or the LAN IP.

SSL required — set MONPG_DB_SSLMODE=require (or verify-full for stricter setups with a CA file).

If you're stuck

Open [email protected]. Include your organization name, the server name, and a rough timestamp of when the problem started. We can see logs on our side and respond within one business day. Faster on the Business and Enterprise plans.