# Troubleshooting

Symptoms first. Each one names the check that tells you which cause you have,
then links to the page that explains the fix.

Most of these are quiet failures. **The collector reports healthy, metrics
arrive, and one capability is simply absent**, which is why they are worth
listing by what you see rather than by what is wrong.

## Nothing has arrived yet

Give it a few minutes before assuming a fault. The PostgreSQL receiver collects
on a 10 second interval by default, but a first run also has to discover
databases, capture schema and take a first statistics sample.

If nothing has appeared after that, work through the three checks below in
order. They are ordered by how often each is the cause.

## The collector cannot connect

Check the collector's own logs first. It says which stage failed, and the three
causes look different:

- **Network.** The collector connects outbound over 443 to DBGorilla, and
  separately to your database on its own port. A database unreachable from the
  container is the common case in Docker and Kubernetes, where `localhost` means
  the container, not the host.
- **Credentials.** The login in your collector config must exist and be allowed
  to connect to every database you listed.
- **TLS.** See [certificate rejected](#a-certificate-was-rejected) below.

## A certificate was rejected

`verify-full` and `verify-ca` fail when your server presents a certificate from
an internal authority, because the collector container has no reason to hold
your CA. **This is the usual outcome with Kubernetes-operator-managed
PostgreSQL**, whose certificates are issued internally.

Either mount your CA into the container and point `ca_cert` at it, or use
`require`, which keeps the connection encrypted but skips verification.

[Choosing `ssl_mode`](/docs/getting-started/collector-installation/overview/#choosing-ssl_mode)
covers the trade-off.

## The Query Performance page is empty

Almost always `pg_stat_statements` is not loaded. It is the PostgreSQL extension
that records how long each statement takes, and every query-level feature reads
from it.

```sql
SELECT * FROM pg_available_extensions WHERE name = 'pg_stat_statements';
SHOW shared_preload_libraries;
```

Without it the collector still connects and still reports host metrics, database
size, table statistics and topology, so **nothing looks broken**. Loading it
needs a full server restart, not a reload.

[pg_stat_statements](/docs/getting-started/collector-installation/overview/#pg_stat_statements)
has the steps, including the `ALTER SYSTEM SET` caution that costs people another
restart.

## Query text is cut off

The database truncated it before DBGorilla saw it, so this is a server setting
rather than a display problem.

On **MySQL**, the collector's `digest_text_limit` caps stored statement text at
120 characters by default. A statement whose text ends in `...` is truncated, and
the collector skips `EXPLAIN` for it, because explaining a partial statement
produces a plan for something the database never ran.

On **PostgreSQL**, `track_activity_query_size` caps the text `pg_stat_statements`
retains. Raising it needs a restart.

## Schema capture fails but everything else works

The clearest symptom of a permissions gap, and the quietest: metrics arrive
normally while `permission denied for table ...` is logged as a warning that
retries forever.

`pg_monitor` alone is not enough. Schema capture runs `pg_dump`, which must
`SELECT` every table it reads, and the `USAGE` and `SELECT` grants apply only to
the database and schema you ran them in.

The other half of this is tables created *after* you granted:
`ALTER DEFAULT PRIVILEGES` without `FOR ROLE` covers only tables created by the
role that ran it, so an application creating its own tables is not covered.

[Database grants](/docs/getting-started/collector-installation/overview/#database-grants)
has the full statement set and the query that lists which roles own tables.

## Still stuck

Email **[support@dbgorilla.com](mailto:support@dbgorilla.com)**.

Send the collector's logs and your collector configuration **with the database
password removed**, and say which of the sections above you have already ruled
out. That is usually the difference between one reply and four.