Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

IntelliJ IDEA Test Connection fails for a PostgreSQL data source

ErrorTest Connection in the data source properties reports a failure

Short answer

When Test Connection fails, work from the bottom up. First confirm the host and port answer outside the IDE, then confirm the driver files are downloaded, then the SSL or SSH settings. IntelliJ's own guide lists these checks, in that order, with the Windows temp path as a rare cause.

  • Applies to IntelliJ IDEA (current release), PostgreSQL 17, macOS, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check from a terminal that the host and port accept connections. If this fails, the problem is the server or network, not IntelliJ.

    pg_isready -h localhost -p 5432
  2. 2Match what you see, then jump to its fix

    1. 1A 'Download missing driver files' link shows under the connection settingsDriver files are not downloadedFix
    2. 2pg_isready says no response, or the port in the URL differs from the server'sHost, port or credentials do not match the serverFix
    3. 3Terminal works only through a tunnel, or the server insists on SSLSSL or an SSH tunnel is required, or set up wronglyFix
    4. 4Windows user name with accents; all other checks passThe Windows temp path has non-ASCII charactersFix

What does the error look like?

  • Test Connection in the data source properties reports a failure
  • Connection to localhost:5432 refused.

Cause 1 of 4

Driver files are not downloaded

1Check

The data source cannot work without its JDBC driver. IntelliJ shows the link at the bottom of the connection settings when files are missing.

echo "Open Data Source Properties and look for the link under the form"

2Fix

Click Download missing driver files, wait for it to finish, then test again. If a different driver version is needed for your server, pick it in the Drivers settings.

echo "Database tool window > Data Source Properties > Download missing driver files"

3Verify

Test Connection now reports success.

echo "Click Test Connection"

Confirmed by jetbrains.com

Did this fix it?

Cause 2 of 4

Host, port or credentials do not match the server

1Check

The default PostgreSQL port is 5432 but real servers often differ. For a local database use localhost or 127.0.0.1. The URL format is jdbc:postgresql://host:port/database.

sudo ss -ltnp | grep postgres
pg_isready -h 127.0.0.1 -p 5432

2Fix

Enter the real host, port, user, password and database. With a Docker container, publish the port with -p and use the published one in the IDE.

jdbc:postgresql://127.0.0.1:5432/mydb

3Verify

Test Connection succeeds.

psql "postgresql://myuser@127.0.0.1:5432/mydb" -c "SELECT 1"

Confirmed by jetbrains.com

Did this fix it?

Cause 3 of 4

SSL or an SSH tunnel is required, or set up wrongly

1Check

The SSH/SSL tab holds the CA, client certificate and key files; PEM files are recommended. A self-signed certificate can fail with a newer driver.

openssl s_client -starttls postgres -connect db.example.com:5432 </dev/null | head

2Fix

Turn SSL on or off to match the server, load the PEM files, or use the IDE's SSH tunnel. As a stopgap for self-signed certificates, the guide suggests temporarily using an older driver.

echo "Data Source Properties > SSH/SSL tab"

3Verify

Test Connection succeeds with the SSH/SSL tab settings.

echo "Click Test Connection"

Confirmed by jetbrains.com

Did this fix it?

Cause 4 of 4

The Windows temp path has non-ASCII characters

1Check

The guide says the temp directory path must not contain non-ASCII characters.

echo %TEMP%

2Fix

Point Java at a clean temp folder in idea.vmoptions, then restart the IDE.

-Djava.io.tmpdir=C:\temp

3Verify

Test Connection works after restart.

echo "Click Test Connection"

Confirmed by jetbrains.com

Did this fix it?

How do I stop it coming back?

  • Keep the port in a project README or .env so the IDE and the app use the same one.
  • Use the same PostgreSQL JDBC driver family the app uses, to catch SSL differences early.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.