Learn how to resolve connection errors
This topic describes how to resolve connection errors you may encounter when using Neon. The errors covered include:
- The endpoint ID is not specified
- Password authentication failed for user
- Couldn't connect to compute node
- Can't reach database server
- Error undefined: Database error
Connection problems are sometimes related to a system issue. To check for system issues, please refer to the Neon status page.
The endpoint ID is not specified
With older clients and some native Postgres clients, you may receive the following error when attempting to connect to Neon:
This error occurs if your client library or application does not support the Server Name Indication (SNI) mechanism in TLS.
Neon uses compute endpoint IDs (the first part of a Neon domain name) to route incoming connections. However, the Postgres wire protocol does not transfer domain name information, so Neon relies on the Server Name Indication (SNI) extension of the TLS protocol to do this.
SNI support was added to the
libpq (the official Postgres client library) in version 14, which was released in September 2021. Clients that use your system's
libpq library should work if you
libpq version is >= 14. On Linux and macOS, you can check your
libpq version by running
pg_config --version. On Windows, check the
libpq.dll version in your Postgres installation's
bin directory. Right click on the file, select Properties > Details.
If a library or application upgrade does not help, there are several workarounds, described below, for providing the required domain name information when connecting to Neon.
A. Pass the endpoint ID as an option
Neon supports a connection option named
endpoint, which you can use to identify the compute endpoint you are connecting to. Specifically, you can add
options=endpoint%3Dep-mute-recipe-123456 as a parameter to your connection string, as shown in the example below. The
%3D is a URL-encoded
endpoint connection option was previously named
project option is deprecated but remains supported for backward compatibility.
endpoint option works if your application or library permits it to be set. Not all of them do, especially in the case of GUI applications.
B. Use libpq key=value syntax in the database field
If your application or client is based on
libpq but you cannot upgrade the library, such as when the library is compiled inside of a an application, you can take advantage of the fact that
libpq permits adding options to the database name. So, in addition to the database name, you can specify the
endpoint option, as shown below. Replace
<endpoint_id> with your compute's endpoint ID, which you can find in your Neon connection string. It looks similar to this:
C. Set verify-full for golang-based clients
If your application or service uses golang Postgres clients like
lib/pg, you can set
sslmode=verify-full, which causes SNI information to be sent when you connect. Most likely, this behavior is not intended but happens inadvertently due to the golang's TLS library API design.
D. Specify the endpoint ID in the password field
Another supported workaround involves specifying the endpoint ID in the password field. So, instead of specifying only your password, you provide a string consisting of the
endpoint option and your password, separated by a semicolon (
;) or dollar sign character (
$), as shown in the examples below. Replace
<endpoint_id> with your compute's endpoint ID, which you can find in your Neon connection string. An
endpoint_id looks similar to this:
Using a dollar sign (
$) character as a separator may be required if a semicolon (
;) is not a permitted character in a password field. For example, the AWS Database Migration Service (DMS) does not permit a semicolon character in the Password field when defining connection details for database endpoints.
This approach causes the authentication method to be downgraded from
scram-sha-256 (never transfers a plain text password) to
password (transfers a plain text password). However, the connection is still TLS-encrypted, so the level of security is equivalent to the security provided by
https websites. We intend deprecate this option when most libraries and applications provide SNI support.
Clients on the list of drivers on the PostgreSQL community wiki that use your system's
libpq library should work if your
libpq version is >= 14.
Neon has tested the following drivers for SNI support:
|Postgrex||Elixir||✓||Requires ssl_opts with server_name_indication|
|github.com/lib/pq||Go||✓||Supported with macOS Build 436, Windows Build 202, and Ubuntu 20, 21 and 22|
|pgx||Go||✓||SNI support merged with v5.0.0-beta.3 yet|
|pg8000||Python||✓||Requires scramp >= v1.4.3, which is included in pg8000 v1.29.3 and higher|
Password authentication failed for user
The following error is often the result of an incorrectly defined connection information, or the driver you are using does not support Server Name Indication (SNI).
Check your connection to see if it is defined correctly. Your Neon connection string can be obtained from the Connection Details widget on the Neon Dashboard. It appears similar to this:
For clients or applications that require specifying connection parameters such as user, password, and hostname separately, the values in a Neon connection string correspond to the following:
- Port number:
5432(Neon uses default Postgres port,
5432, and is therefore not included in the connection string)
- Database name:
neondbis the ready-to-use database created with each Neon project. Your database name may differ.)
If you find that your connection string is defined correctly, see the instructions regarding SNI support outlined in the preceding section: The endpoint ID is not specified.
Couldn't connect to compute node
This error arises when the Neon proxy, which accepts and handles connections from clients that use the Postgres protocol, fails to establish a connection with your compute. This issue sometimes occurs due to repeated connection attempts during the compute's restart phase after it has been idle due to Auto-suspension (scale to zero). Currently, the transition from an idle state to an active one takes a few seconds.
Consider these recommended steps:
- Visit the Neon status page to ensure there are no ongoing issues.
- Pause for a short period to allow your compute to restart, then try reconnecting.
- Try connecting with psql to see if a connection can be established.
- Review the strategies in Connection latency and timeouts for avoiding connection issues due to compute startup time.
If the connection issue persists, please reach out to Support.
Can't reach database server
This error is sometimes encountered when using Prisma Client with Neon.
A compute node in Neon has two main states: Active and Idle. Active means that Postgres is currently running. If there are no active queries for 5 minutes, the activity monitor gracefully places the compute node into an idle state to save energy and resources.
When you connect to an idle compute, Neon automatically activates it. Activation typically happens within a few seconds. If the error above is reported, it most likely means that the Prisma query engine timed out before your Neon compute was activated. For dealing with this connection timeout scenario, refer to the connection timeout instructions in our Prisma documentation. Our connection latency and timeout documentation may also be useful in addressing this issue.
Error undefined: Database error
This error is sometimes encountered when using Prisma Migrate with Neon.
Prisma Migrate requires a direct connection to the database. It does not support a pooled connection with PgBouncer, which is the connection pooler used by Neon. Attempting to run Prisma Migrate commands, such as
prisma migrate dev, with a pooled connection causes this error. To resolve this issue, please refer to our Prisma Migrate with PgBouncer instructions.