Connection errors by message

Find the message you saw, then follow its fix. Each section starts with the text as Alcuin shows it, so a search for the message lands here.

Where the message appears

Test connection, in the connection’s form, shows a box with a heading that names the step that failed, a row of steps (SSH tunnel, Reached server, Encryption, Sign in), the message, and a line of advice. Connect in the launcher shows the same heading above the message; when Alcuin was reopening a connection you had open, it starts with Couldn't reconnect to, the connection’s name and a colon. A saved connection tested from the launcher’s Test connection… says the heading in a toast, with the message as its detail.

123

A test that failed at Sign in.

1. 1The steps, up to the one that failed.
2. 2The field to change is outlined.
3. 3Test again, and Copy details.

Heading	The step that failed
Couldn't open the SSH tunnel	The SSH tunnel, when the connection uses one
Couldn't reach the server	The network: host and port
Couldn't set up encryption	TLS, as set in Encryption
Couldn't sign in	The user, the password and the database
The server refused the connection	The server answered, then turned the connection away

Steps before the one that failed worked, so leave their settings alone. Most messages here carry the code ALC-1001: Could not connect. An SSH host key that isn’t known carries ALC-1003, and one that changed carries ALC-1004. Copy details puts the code first.

Alcuin connects with its own Postgres driver, not with libpq. Messages from the Postgres server read the same as they do in psql. When the network or TLS fails, Alcuin says what happened in one sentence that names the host and port and ends with the system’s code in parentheses, such as (ECONNREFUSED). These read differently from psql’s messages, so each section names both. Copy details puts the driver’s own words, such as connect ECONNREFUSED 10.0.0.5:5432, on its last line.

no pg_hba.conf entry for host

no pg_hba.conf entry for host "203.0.113.7", user "app", database "shop", no encryption

Heading: Couldn't sign in.

The server was reached, but no line in its pg_hba.conf lets this user connect to this database from your address with this kind of connection. The message comes from the server, with SQLSTATE 28000. Its last part says how you came: no encryption, SSL encryption or GSS encryption.

1. If it ends no encryption, the server may accept your address over TLS only. Set Encryption to Required, verify server, or Required if you cannot get the CA file. See TLS and sslmode.
2. Check that User and Database are the ones the server’s administrator expects. The rule matches on both.
3. Otherwise ask whoever runs the server to add a line for your address, user and database. See The pg_hba.conf file in the Postgres manual.

The address in the message is the one the server sees. Behind a NAT, a VPN or an SSH tunnel it is not your machine’s own address. Through Alcuin’s SSH tunnel it is the bastion’s.

password authentication failed for user

password authentication failed for user "app"

Heading: Couldn't sign in. SQLSTATE 28P01.

The server refused the password. Postgres gives the same message when the user does not exist, so a wrong User reads like a wrong password.

1. Check User. Names are case-sensitive.
2. Type the password again in Password and click Test again. A password in a pasted URL must be percent-encoded; see Connection URLs.
3. If the password comes from a command, such as an IAM or Entra token, Alcuin asks the command once more for a fresh password before it gives up. If it still fails, run the command in a terminal and check that the token is for this host, port and user. See Passwords from a command.

If you changed the host, port, user or tunnel of a saved connection, you may see this instead:

The saved password was saved for the server this connection pointed at before, so it was not sent to this one. Enter it again for this server.

Alcuin keeps a saved password for the server it was saved for. Type it again and save.

The server asked for a password, and there was none to send

The server asked for a password, and there was none to send: the connection saves none, and the password file (.pgpass) has none for this host, port, database and user. Enter the password, or add a line for this connection to the password file.

Heading: Couldn't sign in.

The server wants a password and the connection has none to give, so Alcuin sends nothing. You see this after importing from pgAdmin or DBeaver, whose passwords don’t come over.

1. Enter the password in Password and click Test again.
2. If the connection takes its password from .pgpass, check that a line matches this host, port, database and user, and that the file is readable by you only. See Take the password from .pgpass.

database "…" does not exist

database "shop" does not exist

Heading: Couldn't sign in. SQLSTATE 3D000.

The server was reached and the user may sign in, but there is no database by that name. Alcuin counts the database as part of signing in, so the Sign in step fails.

1. Check Database. A name created with quotes, such as "Shop", is case-sensitive.
2. For a saved connection opened from the launcher, Alcuin adds This database is no longer on the server. and offers Remove connection…, for a database that was dropped.

role "…" does not exist

role "app" does not exist

Heading: Couldn't sign in. SQLSTATE 28000.

The server has no role by that name. Most servers answer a wrong user with password authentication failed for user instead, so you see this one only where pg_hba.conf lets the user in without a password check.

Check User. Names are case-sensitive.

The password command exited with code 1

The password command exited with code 1. If it needs you to sign in first (aws sso login, az login, gcloud auth login, vault login), do that in a terminal, then try again.

Heading: Couldn't sign in. The advice reads Nothing was sent to the server. Run the command in a terminal to see why; if it needs you to sign in first, do that there, then test again., and the box shows the last lines the command wrote to its error output.

The connection takes its password from a command, and the command failed before Alcuin reached the server. The other messages it can give:

Message	What to do
The password command printed nothing.	Run the command in a terminal; it usually needs you to sign in first
The password command did not finish within 30 seconds.	It is probably waiting for a sign-in or a prompt. Sign in in a terminal first
Couldn't find aws. Check that it is installed and on the PATH your login shell sets, or give its full path.	Install the tool, or give its full path in Command
Alcuin does not run sign-in commands: they open a browser or ask for input.	Sign in from a terminal, then use a command that prints the password
You chose not to run the password command, so Alcuin did not connect.	Change the command, or restart Alcuin to be asked again
"|" is shell syntax. or "$" would expand in a shell.	Alcuin runs the command without a shell. Put the pipeline or variable in a script

1. Run the command in a terminal and read what it prints.
2. If it needs you to sign in first, such as aws sso login or gcloud auth login, do that in the terminal.
3. Click Test again.

See Passwords from a command.

Connection refused

Nothing is accepting connections at 10.0.0.5:5432 (ECONNREFUSED).

Heading: Couldn't reach the server.

psql says Connection refused and asks whether the server is running and accepting TCP/IP connections. Something answered at that address, but nothing listens on that port.

1. Check Host and Port. Postgres listens on 5432 unless it was set up otherwise.
2. Check that the server is running.
3. By default Postgres listens only on localhost. For a server on another machine, check listen_addresses.
4. For a server in Docker, check that the container publishes the port, and use the published port.

The name db.example.com doesn't resolve to an address (ENOTFOUND). means the host name does not resolve: check Host, and your VPN. There's no network route to db.example.com (EHOSTUNREACH)., or (ENETUNREACH), means this computer has no way to reach that address, often because a VPN is not connected.

Through an SSH tunnel, a refusal at the database’s end reads the SSH server could not reach db.internal:5432: …, under Couldn't open the SSH tunnel. The bastion reached for Host and Port and nothing answered. Host is resolved by the bastion, so it must be a name the bastion knows. See SSH tunnels.

timeout expired

Nothing answered at db.example.com:5432 within 15 seconds (ETIMEDOUT).

Heading: Couldn't reach the server.

psql says timeout expired. Nothing answered within 15 seconds. The packets went nowhere: a firewall or cloud security group dropped them, the address is not routable from your network, or a VPN is not connected. Alcuin always waits 15 seconds; a connect_timeout in a pasted URL is ignored.

1. Check Host and Port.
2. Check the firewall or security group in front of the server. A cloud database often accepts only listed addresses: add yours. See Cloud providers.
3. Connect your VPN, or, when the server is only reachable from a private network, turn on Connect through SSH.
4. From a terminal, run pg_isready -h <host> -p <port>. If that waits too, the problem is the network, not Alcuin.

Through an SSH tunnel, Timed out while waiting for handshake under Couldn't open the SSH tunnel means the bastion did not answer within 15 seconds: check SSH host, SSH port and your network. the SSH server did not open a channel to db.internal:5432 within 15 s means the bastion answered but didn’t reach the database.

certificate verify failed

Alcuin does not show OpenSSL’s certificate verify failed. It shows the reason the check failed, under Couldn't set up encryption:

Message	Meaning
The server's certificate is self-signed and isn't trusted (SELF_SIGNED_CERT_IN_CHAIN).	The chain ends in an authority Alcuin does not trust
The server's certificate is self-signed and isn't trusted (DEPTH_ZERO_SELF_SIGNED_CERT).	The server’s certificate signs itself
unable to get local issuer certificate	Alcuin has no certificate for the authority that signed it
unable to verify the first certificate	The server sent its certificate without the one that signed it
The server's certificate has expired (CERT_HAS_EXPIRED).	The certificate’s end date has passed, or this computer’s clock is wrong
The server's certificate is for a different name than db.example.com (ERR_TLS_CERT_ALTNAME_INVALID).	With Required, verify server, the certificate names a different host from the one in Host

These come up only when Encryption checks the certificate: Required, verify server, Required, verify certificate, or any setting with CA certificate set.

1. Set CA certificate to your provider’s root certificate. TLS and sslmode says where each provider publishes it.
2. For a private authority that your operating system already trusts, type system in CA certificate.
3. For a host name mismatch, connect with a name the certificate lists, or choose Required, verify certificate. Through a port forward on localhost, Required, verify certificate is the right setting.
4. For an expired certificate, check this computer’s date first, then tell whoever runs the server.

Do not drop to Required to make the message go away unless you cannot get the CA file: Required encrypts, but does not prove you reached the right server.

If the problem is the CA file itself, see the next section.

Could not read the CA certificate file

Could not read the CA certificate file: ~/certs/ca.pem

Heading: Couldn't set up encryption. Alcuin reads CA certificate, Client certificate and Client key at each connect, and stops before TLS starts when one can’t be used:

Message	What to do
Could not read the CA certificate file: …, or the same for the client files	Check the path. A path may start with ~/
The CA certificate path is not a file: …	Choose the file, not its folder
The CA certificate file is not a PEM certificate: …	Convert a DER file with openssl x509 -inform der -in ca.der -out ca.pem
The CA certificate file is too large: …	Files over 1 MB are refused. Check that it is the certificate
The client certificate needs its key. or The client key needs its certificate.	Set both Client certificate and Client key, or neither
The client key has a passphrase, which Alcuin cannot use yet.	Save a copy without one with openssl pkey -in key.pem -out plain.pem and choose that

See Set the certificate files.

SSL SYSCALL error: EOF detected

Alcuin does not show this libpq message. When the server, or something between you and it, closes the connection without a word, Alcuin shows one of these:

• The server closed the connection before encryption was set up (ECONNRESET). It may not accept TLS on this port., under Couldn't set up encryption: the connection closed during the TLS handshake.
• The server closed the connection before it was set up (ECONNRESET). or Connection terminated unexpectedly, under Couldn't reach the server: it closed before the server said anything else.
• Connection lost. Reconnecting…, once you are connected: it closed while you were working. See ALC-1002: Connection lost.

A closed handshake usually means the port answers but is not Postgres’s TLS: a load balancer or proxy that expects TLS from the first byte, a port forward to the wrong service, or a pooler with TLS set up differently from the server. A connection dropped later usually means an idle timeout in a pooler, load balancer or firewall, or a server restart.

1. Check Port: is it the server’s, or a proxy’s?
2. Try Encryption set to Required, then Off on a network you trust. If Off works and Required does not, the server or the proxy in front of it has TLS turned off or broken.
3. Check the server’s log for the same moment. A crash or restart shows there.
4. Behind a pooler, see Connection poolers.

server does not support SSL

The server does not support SSL connections

Heading: Couldn't set up encryption.

psql says server does not support SSL, but SSL was required. Encryption asks for TLS, and the server answered that it has TLS turned off.

1. Turn TLS on at the server. See Secure TCP/IP connections with SSL.
2. For a server on this machine, or a network you trust, choose Preferred or Off.

With Preferred, Alcuin does not stop here: it connects in plain text. Anyone between you and the server can give that answer, so do not use Preferred across networks you don’t control. See TLS and sslmode.

The server asked for the password in clear text

The server asked for the password in clear text, and this connection doesn't check the server's certificate, so Alcuin didn't send it. Set Encryption to Required, verify server (with the server's CA certificate if it isn't signed by a public authority), or have the server use SCRAM (password_encryption = scram-sha-256).

Heading: Couldn't sign in. The message can also say MD5 instead of clear text.

The server asked for the password in a form someone in between could read or crack, and the connection does not prove which server it reached. Alcuin sends such a password, whether saved, from a command or from .pgpass, only over TLS that checks the certificate, an SSH tunnel, or to a server on this machine.

1. Set Encryption to Required, verify server, with the server’s CA where it has its own.
2. Or have the server store passwords as SCRAM: set password_encryption = scram-sha-256, set the password again, and use scram-sha-256 in pg_hba.conf.

See TLS and sslmode.

SSH host key not known or changed

The SSH server bastion.example.com is not one this machine knows. Its key's fingerprint is SHA256:…: check it with whoever runs the server, then trust it in the connection's settings.

Heading: Couldn't open the SSH tunnel. This is the first connect through that bastion from this machine. Compare the fingerprint with the one the bastion’s owner gives you, then click Trust this key. See ALC-1003: Unknown SSH host key.

The SSH server bastion.example.com presented a different key (SHA256:…) from the one trusted for it. Someone may be posing as it. If the server's key really changed, trust the new one in the connection's settings.

Heading: Couldn't open the SSH tunnel. ssh in a terminal says REMOTE HOST IDENTIFICATION HAS CHANGED for the same thing. Find out why the key changed before you click Trust the new key. See ALC-1004: SSH host key changed.

In the launcher these messages show without the buttons. Right-click the connection, choose Edit…, and click Test connection in the form: the fingerprint and its button show there.

All configured authentication methods failed

All configured authentication methods failed

Heading: Couldn't open the SSH tunnel. The bastion refused your key, your agent’s keys or your password. Other messages at this step come before Alcuin tries to sign in:

Message	What to do
no SSH agent is running (SSH_AUTH_SOCK is not set)	Start an agent, or choose Private key file. An app started from the Dock doesn’t see variables set only in ~/.zshrc
no private key file set, could not read the private key file or the key path is not a file	Check Key path
that file is not an SSH private key or that file is too large to be a private key	Choose the private key, not the .pub file. OpenSSH, PEM and PuTTY keys work
no SSH password saved	Enter SSH password

1. Check SSH host, SSH port and SSH user.
2. From a terminal, run ssh -p <port> <user>@<host>. If that fails too, fix SSH access first.
3. With SSH agent, check that the agent holds the key: ssh-add -l.

See SSH tunnels.

prepared statement "s1" already exists

prepared statement "s1" already exists

SQLSTATE 42P05, in a query tab, behind a pooler in transaction mode.

A transaction pooler hands each statement outside a transaction to whichever server session is free. A PREPARE s1 you ran earlier, or another client ran, stays in the session it ran in. When your next PREPARE s1 lands in that session, the server refuses it. The reverse, an EXECUTE s1 that lands in a session that never saw the PREPARE, fails with prepared statement "s1" does not exist (SQLSTATE 26000).

Alcuin’s own reads do not name their statements, so they do not cause this. It comes from PREPARE in your own SQL.

1. Connect directly, or through the pooler’s session mode, to work with prepared statements. Connection poolers has the ports for each provider.
2. Or keep PREPARE, EXECUTE and DEALLOCATE inside one BEGIN … COMMIT. A query tab keeps one server session until the transaction ends.

See PREPARE in the Postgres manual.

The server has no free connections

The server has no free connections (sorry, too many clients already). Close idle clients holding connections, or raise max_connections.

Heading: The server refused the connection. Every connection slot is in use. Close idle clients, or raise max_connections. Behind a pooler, the limit may be the pooler’s own; see Connection poolers.

the database system is starting up and the database system is shutting down, under the same heading, mean waiting a moment and clicking Test again.

When it works

Test connection says ✓ Connected in and the time, the server’s version, how it connected (over TLS, through the SSH tunnel or directly) and the user it signed in as. Click Save.

If your message is not here

• Cloud providers has a working setup for each provider to compare against.
• If nothing explains it, save a diagnostics bundle and open an issue. See Logs and the diagnostics bundle.