Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker

ErrorAn exception has been raised that is likely due to a transient failure

Short answer

The transient failure message comes from EF Core's retry layer, which hides the underlying connection error. Read the inner exception. For a PostgreSQL container the real cause is usually an unpublished port or a connection string with the wrong host port.

  • Applies to EF Core 8, Npgsql.EntityFrameworkCore.PostgreSQL 8, PostgreSQL 16, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Docker which host ports the container publishes. If the PostgreSQL port is missing from the output, your app on the host has nothing to connect to.

    docker container inspect my-postgres --format "{{json .NetworkSettings.Ports}}"
  2. 2Match what you see, then jump to its fix

    1. 1The inspect output shows no HostPort for 5432/tcp, or the container was started without -pThe container port is not published to the hostFix
    2. 2The container was started with a mapping such as 5433:5432 while the connection string says nothing about the portThe connection string uses a different port than the one you publishedFix
    3. 3The log shows only the transient failure message, and the app waits before it failsRetry on failure hides the real exceptionFix

What does the error look like?

  • An exception has been raised that is likely due to a transient failure
  • The query fails only after a delay, because the connection is retried several times

Cause 1 of 3

The container port is not published to the host

1Check

Docker blocks access to ports that were not published. A container on a bridge network is reachable from the host only through a published port.

docker container inspect my-postgres --format "{{json .NetworkSettings.Ports}}"

2Fix

Recreate the container with a port mapping in the form hostPort:containerPort. Add 127.0.0.1 in front if only the local machine should reach it.

docker run --name my-postgres -p 127.0.0.1:5432:5432 [your usual options] postgres:16

3Verify

The inspect command now shows a HostPort, and the app connects.

docker container inspect my-postgres --format "{{json .NetworkSettings.Ports}}"

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The connection string uses a different port than the one you published

1Check

Npgsql's Port parameter defaults to 5432. If you mapped the container to another host port, the app still dials 5432.

grep -rn "Host=\|Port=" appsettings*.json

2Fix

Put the host side of your -p mapping into the connection string.

"ConnectionStrings": {
  "Default": "Host=localhost;Port=5433;Database=app;Username=postgres;Password=secret"
}

3Verify

Start the app. The first query succeeds.

dotnet run

Confirmed by npgsql.org

Did this fix it?

Cause 3 of 3

Retry on failure hides the real exception

1Check

The Npgsql provider's execution strategy retries errors it considers transient and relies on NpgsqlException.IsTransient. The message you see comes from that retry layer, and the exception that triggered it is available as InnerException.

grep -rn "EnableRetryOnFailure" --include=*.cs .

2Fix

Log the inner exception, or remove EnableRetryOnFailure while you debug so the connection error comes out on the first attempt.

options.UseNpgsql(connectionString);   // without options => options.EnableRetryOnFailure()

3Verify

The exception now names the real problem, such as a refused connection.

dotnet run

Confirmed by npgsql.org

Did this fix it?

How do I stop it coming back?

  • Keep the container's -p mapping and the connection string port in one shared place such as a compose file.
  • Log exception.InnerException wherever a database call is wrapped by a retry strategy.
  • Check the connection with a plain NpgsqlConnection.Open before you suspect EF Core.

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?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

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