Powering next gen AI apps with Postgres 🚀 Learn More
Connect/Connection issues

Connection errors

Learn how to resolve connection errors

This topic describes how to resolve connection errors you may encounter when using Neon. The errors covered include:

info

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 = sign.

note

The endpoint connection option was previously named project. The project option is deprecated but remains supported for backward compatibility.

The 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: ep-mute-recipe-123456.

C. Set verify-full for golang-based clients

If your application or service uses golang Postgres clients like pgx and 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: ep-mute-recipe-123456.

or

note

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.

Libraries

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:

DriverLanguageSNI SupportNotes
npgsqlC#
PostgrexElixirRequires ssl_opts with server_name_indication
github.com/lib/pqGoSupported with macOS Build 436, Windows Build 202, and Ubuntu 20, 21 and 22
pgxGoSNI support merged with v5.0.0-beta.3 yet
go-pgGorequires verify-full mode
JDBCJava
node-postgresJavaScriptRequires the ssl: {'sslmode': 'require'} option
postgres.jsJavaScriptRequires the ssl: 'require' option
asyncpgPython
pg8000PythonRequires scramp >= v1.4.3, which is included in pg8000 v1.29.3 and higher
PostgresClientKitSwift
PostgresNIOSwift
postgresql-clientTypeScript

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:

  • User: daniel
  • Password: f74wh99w398H
  • Hostname: ep-white-morning-123456.us-east-2.aws.neon.tech
  • Port number: 5432 (Neon uses default Postgres port, 5432, and is therefore not included in the connection string)
  • Database name: neondb (neondb is 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:

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.

Need help?

Send a request to support@neon.tech, or join the Neon community forum.

Edit this page
Was this page helpful?