Connection failures and what our error phrases mean
Every scan begins with a connection attempt to your database over the ordinary Postgres wire protocol.
When that attempt fails, the driver produces an error message written for engineers debugging a local setup. RowShield does not pass those messages through to the interface. Instead the probe maps each failure class onto one of a small number of fixed phrases, and this article lists the whole catalogue, explains what each phrase means in practice, and describes why the substitution exists at all.
The fixed phrase catalogue
These are all the connection phrases the probe can report, together with their usual causes:
Connection refused — the hostname resolved and the network path was traversed, but nothing answered on the database port. The usual causes are a paused project, a firewall or network restriction, or a pooler endpoint that has been retired.
DNS lookup failed — the project hostname no longer resolves. This most often follows a restore from pause that produced a new project hostname, or a mistake made when the integration was first configured.
TLS handshake rejected — the socket opened but the TLS negotiation did not complete. This is seen when a corporate proxy intercepts outbound traffic, or when a project is mid-resume and not yet ready to serve.
Authentication rejected — the server spoke the protocol but declined the role or password. Rotate the stored credential in the integration settings and trigger a fresh scan.
Connection timed out — no response arrived inside the probe window. This normally indicates an intermediary silently dropping packets rather than a fault in your application.
Probe queue unavailable — the failure was on our side. The scan is retried automatically and no finding is recorded against your project.
Why raw driver errors are suppressed
Raw driver messages are accurate but indiscreet. They routinely embed the resolved hostname, pooler endpoints, IPv6 addresses of intermediate hops, and occasionally the full connection string with its parameters. Rendering that text on a project page would hand infrastructure details to anyone who can open the page, including teammates who need the verdict but not the topology. Error text also travels far beyond where it first appeared, copied into tickets, chat threads and browser extensions.
The second reason is stability. Driver libraries reword their messages between releases, which would make alerts noisy and dashboards inconsistent for no operational gain. Fixed phrases give you a stable vocabulary: you can filter, count and alert on them, and the meaning does not shift underneath you between driver versions.
If you genuinely need the raw diagnostic detail, run the CLI from your own machine. There the full driver message is printed locally and never leaves your network.
First steps when a probe fails
Work through this order. First, confirm the project is awake: a paused instance refuses connections by design, and resuming it clears most refusal and timeout phrases. Second, check whether the credential stored in the integration still matches a valid role; recent rotations elsewhere in your tooling are a frequent culprit behind authentication phrases. Third, rule out network intermediaries by running a scan with the CLI from a machine outside the restricted network, which isolates proxies and VPN rules cleanly.
If the phrase persists after these checks, contact support and quote the scan identifier shown beside the failure. The identifier lets us retrieve the probe's structured diagnostics, including timings and the failure class, without asking you to paste anything sensitive. We aim to respond within one business day for connection failures, because a probe that cannot connect leaves the rest of your posture unverified until it is resolved.
Did this answer your question? If not, tell us what is missing — article corrections go straight to the person who maintains it.