Fix Neon SSL Required Connection Errors (2026)

The neon.errors.NeonError: SSL Required error means your application is trying to connect to Neon using an unencrypted (plain text) connection, but Neon’s security policy mandates encrypted (SSL/TLS) connections.

Here are the common reasons and how to fix them:

1. Your Database URL is Missing the sslmode Parameter:

• Diagnosis: Inspect your connection string. It will likely look something like postgresql://user:password@host:port/dbname.
• Cause: The PostgreSQL client library, by default, might not enforce SSL if not explicitly told to. Neon requires SSL.
• Fix: Append ?sslmode=require to your connection URL. For example: postgresql://user:password@host:port/dbname?sslmode=require.
• Why it works: This tells the PostgreSQL client to refuse any connection that isn’t secured with SSL/TLS.

2. Your Application Code is Not Configuring SSL:

• Diagnosis: Review the database connection code in your application. Look for how the connection string or parameters are being passed to the database driver.
• Cause: Some libraries or frameworks might have their own settings for SSL that override or interact with the connection string’s sslmode.
• Fix (Example with Node.js pg library):

  const { Pool } = require('pg');
  const pool = new Pool({
    connectionString: 'postgresql://user:password@host:port/dbname',
    ssl: {
      rejectUnauthorized: false // Or true if you have the CA cert
    }
  });
  

  Or more directly, ensure sslmode=require is in the connectionString. If you’re using environment variables, ensure the DATABASE_URL includes sslmode=require.
• Why it works: Explicitly telling the driver to use SSL, or ensuring the connection string is correctly formatted, satisfies Neon’s requirement.

3. Incorrect sslmode Value:

• Diagnosis: Check the sslmode parameter in your connection string. Common values are disable, allow, prefer, require, verify-ca, verify-full.
• Cause: Using sslmode=disable or sslmode=allow will attempt a plain text connection, which Neon rejects. sslmode=prefer might fall back to plain text if SSL fails, which is also not allowed.
• Fix: Ensure your sslmode is set to require or a more secure option like verify-ca or verify-full if you’ve configured certificate verification. The most common and generally sufficient setting is sslmode=require. Example: postgresql://user:password@host:port/dbname?sslmode=require.
• Why it works: require guarantees that the connection must be SSL/TLS encrypted.

4. Firewall or Network Restrictions Blocking SSL Ports:

• Diagnosis: Can you connect to Neon from a different network or machine? Try psql from your local machine with the full connection string including sslmode=require.
• Cause: A corporate firewall, VPN, or cloud security group might be configured to block outbound connections on the PostgreSQL port (5432) unless they are explicitly allowed, or it might be interfering with the SSL handshake.
• Fix: Consult your network administrator or cloud provider’s documentation to ensure outbound traffic to your-neon-host.neon.tech on port 5432 is permitted, specifically for SSL/TLS connections. You may need to add a firewall rule.
• Why it works: This removes external network impediments to establishing a secure connection.

5. Outdated PostgreSQL Client Library:

• Diagnosis: Check the version of your PostgreSQL client library (e.g., pg in Node.js, psycopg2 in Python, psql command-line client).
• Cause: Older versions of client libraries might have bugs or incomplete support for modern SSL/TLS protocols and configurations, leading to connection failures even when sslmode=require is used.
• Fix: Update your PostgreSQL client library to the latest stable version. For example, with npm: npm install pg@latest. For psql, download the latest version from the PostgreSQL website.
• Why it works: Newer versions contain fixes and improved compatibility with SSL/TLS standards, ensuring a successful handshake.

6. Incorrect SSL Certificate Validation Configuration (Less Common for Neon Direct Connect):

• Diagnosis: If you are using sslmode=verify-ca or sslmode=verify-full and encountering issues, check your local certificate store or the path to the CA certificate file specified in your connection parameters.
• Cause: Neon uses standard, trusted SSL certificates. If your client is configured to verify the server’s certificate against a specific CA bundle, and that bundle is missing, outdated, or incorrect, the verification will fail. For most direct connections to Neon, sslmode=require is sufficient and avoids the need for client-side CA configuration.
• Fix: For most Neon use cases, switch to sslmode=require. If you absolutely need certificate verification, ensure your client has the correct root CA certificates installed or provided. You can typically find the necessary CA information in your operating system’s trust store or by downloading them from a reputable source.
• Why it works: Using sslmode=require bypasses the client-side certificate validation step, allowing the connection to proceed if the SSL handshake is otherwise successful.

If you’ve addressed all these points and still see the error, double-check your Neon project’s connection details (host, port, user, password, database name) for any typos.

The next error you might encounter after fixing SSL is related to authentication if your password or user is incorrect.