Skip to content

Troubleshooting a PostgreSQL source

When a connection test fails, the step that failed shows a message. Each section below is headed by that message, word for word, and says what usually causes it and what to do. These are the messages the steps of the setup guide can lead to; every message the test can show, in every step, is listed in the connection test reference.

A failed step stops the steps after it, so fix the first failed step and test again. Some messages end a step with a warning instead: the source can still be used, and the section says when that matters.

The host name was not found within 5 seconds.

Section titled “The host name was not found within 5 seconds.”

Code: timed_out

The DNS servers for the host name did not answer in time. Test again; if it keeps happening, those DNS servers are not answering, which is for whoever runs the name’s DNS to fix. (A name that does not exist at all, or that leads to a private address, is refused when the source is saved, with its own words.)

Code: unreachable

Nothing accepted the connection on that port, something closed it, or no route led to the address. Check the port (PostgreSQL’s is 5432 unless yours was changed), that the database is running, and that a firewall in front of it does not reject our addresses (step 3 of the setup guide).

Nothing answered within 10 seconds: a firewall dropping the connection is the usual cause.

Section titled “Nothing answered within 10 seconds: a firewall dropping the connection is the usual cause.”

Code: timed_out

Our connection was neither accepted nor refused: something between us and the database dropped it. Allow our addresses where your host keeps its network rules (the security group, the authorized networks, the firewall rules: step 3 of the setup guide).

The host has only IPv6 addresses, and this service connects from IPv4.

Section titled “The host has only IPv6 addresses, and this service connects from IPv4.”

Code: ipv6_only

We connect over IPv4, and the host name has only IPv6 addresses. On Supabase, enable the IPv4 add-on and use the direct connection (step 1 of the setup guide); elsewhere, give the database an IPv4 address.

Code: server_has_no_tls

The server does not accept encrypted connections. Turn on TLS on the server (ssl = on in postgresql.conf, with a certificate), then reload it. Choosing a mode that does not need TLS sends your data in the clear: see TLS.

The server’s certificate is not signed by anything this connection trusts.

Section titled “The server’s certificate is not signed by anything this connection trusts.”

Code: approval_needed

Nothing the connection trusts signed the certificate the server presented. Choose the trust your host needs (on Amazon RDS and Aurora, Amazon RDS; with a private certificate authority, upload its certificate), or approve the certificate the test shows: Approving a certificate.

The certificate is valid, but issued for another name.

Section titled “The certificate is valid, but issued for another name.”

Code: name_mismatch

The certificate is valid, but the host name you connect with is not one it lists, and the step says which names it does list. Connect using one of those names, or, with a certificate authority you chose, use verify-ca: see Approving a certificate.

The server presents a different certificate from the one approved.

Section titled “The server presents a different certificate from the one approved.”

Code: certificate_changed

The source trusts one exact certificate (an approved one), and the server now presents another. Approve the new one only if you know the server renewed its certificate, and after comparing the SHA-256 the test shows with the server’s own: if you expected no change, something may be standing in for your server, and nothing should be approved until you know which. Then start the pipelines: When a certificate changes or ends.

The password was refused. The server says the same for a role that does not exist, or whose password has expired.

Section titled “The password was refused. The server says the same for a role that does not exist, or whose password has expired.”

Code: bad_password

Check the password, and that the role exists with that exact name (step 2 of the setup guide). A role whose password has expired (VALID UNTIL) is refused the same way.

The server’s pg_hba.conf has no line for this connection.

Section titled “The server’s pg_hba.conf has no line for this connection.”

Code: no_hba_line

On a server of your own, pg_hba.conf needs a line that lets the role reach the database from our addresses over TLS, then a reload: hostssl <database> <role> <address> scram-sha-256 (step 3 of the setup guide).

A pg_hba.conf line rejects this connection.

Section titled “A pg_hba.conf line rejects this connection.”

Code: hba_reject_line

pg_hba.conf is read from the top, and the first line that matches a connection decides it: a reject line above yours matches first. Move your hostssl line above it, or narrow the reject line, then reload.

Code: role_cannot_log_in

The role exists, but was created without the right to sign in. As the administrator: ALTER ROLE <role> LOGIN;

The role may not connect to this database.

Section titled “The role may not connect to this database.”

Code: no_connect_privilege

As the administrator: GRANT CONNECT ON DATABASE <database> TO <role>;

The role cannot replicate: it needs the REPLICATION attribute.

Section titled “The role cannot replicate: it needs the REPLICATION attribute.”

Code: not_replication_role

The role may sign in, but not read the change log. Give it the right your host uses, as in step 2 of the setup guide: the REPLICATION attribute, or on Amazon RDS and Aurora GRANT rds_replication TO <role>;.

Code: database_missing

Check the database name in the source: it is the database inside the server, not the server’s or the project’s name.

Code: too_many_connections

Every connection allowed is in use: the server’s (max_connections), or a limit on the role or the database (CONNECTION LIMIT). Check the role’s with SELECT rolconnlimit FROM pg_catalog.pg_roles WHERE rolname = '<role>'; (-1 is no limit) and raise it with ALTER ROLE <role> CONNECTION LIMIT <n>;. Otherwise close connections you do not need, or raise max_connections, which takes a restart.

Your database does not keep the change log a pipeline reads: its wal_level setting is not logical.

Section titled “Your database does not keep the change log a pipeline reads: its wal_level setting is not logical.”

Code: wal_level_not_logical

Logical replication is not on yet, or it was set and the server has not restarted since. Follow step 1 of the setup guide for your host, including its restart.

Every change bookmark (replication slot) the server allows is in use.

Section titled “Every change bookmark (replication slot) the server allows is in use.”

Code: no_free_slot

A warning: every replication slot the server allows (max_replication_slots) exists already, so the next one cannot be made. Raising max_replication_slots is the safe fix; it takes a restart.

To see the slots: SELECT slot_name, slot_type, plugin, database, active, wal_status FROM pg_catalog.pg_replication_slots;. Do not drop a slot because it is inactive: a stopped or paused pipeline’s slot is inactive, and so is the one you create for a pipeline before it first starts. Each pipeline’s page names its own slot. Dropping a pipeline’s slot means every one of its tables must be copied again, and dropping another tool’s breaks that tool. Drop one only when you know nothing uses it any more: SELECT pg_catalog.pg_drop_replication_slot('<slot name>'); (until then it keeps the server’s change log).

Code: no_free_sender

A warning: every replication connection allowed is in use, the server’s (max_wal_senders) or a limit on the role (CONNECTION LIMIT, checked as above). Raise the limit (max_wal_senders takes a restart), or stop a replication reader that is no longer needed.