EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
An exception has been raised that is likely due to a transient failureShort 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.
Fix it fast
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}}"2Match what you see, then jump to its fix
- 1
The inspect output shows no HostPort for 5432/tcp, or the container was started without -pThe container port is not published to the hostFix - 2
The 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
The log shows only the transient failure message, and the app waits before it failsRetry on failure hides the real exceptionFix
- 1
What does the error look like?
An exception has been raised that is likely due to a transient failureThe 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:163Verify
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
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*.json2Fix
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 runConfirmed by npgsql.org
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 runConfirmed by npgsql.org
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
Databases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
A Postgres query in Docker fails with: could not resize shared memory segment
ERROR: could not resize shared memory segment: No space left on device
Postgres in a container hands query memory to parallel workers through the container's /dev/shm.
2 causes, each with a fixDatabases
The Postgres container refuses to start: data directory has invalid permissions
mkdir: cannot create directory ‘/home/postgres/pgdata/data’: permission denied
Postgres starts only when its data directory is owned by the server user and closed to everyone else: mode 0700, or 0750 when group read is enabled.
3 causes, each with a fixDatabases
The postgres container exits when ssl=on and a mounted certificate
the container exits a second after docker compose up, and the log names server.crt or server.key
With ssl=on, PostgreSQL refuses to start if it cannot use the certificate and key.
3 causes, each with a fixDatabases
The Postgres container cannot set permissions on a bind-mounted data folder
chmod: changing permissions of '/var/lib/postgresql/data': Operation not permitted
Postgres needs its data directory owned by the server user with mode 0700.
3 causes, each with a fixDatabases
The Postgres container cannot initialise because its data directory already has files
initdb: error: directory "/var/lib/postgresql/data" exists but is not empty
initdb refuses to run in a directory that already has anything in it.
3 causes, each with a fix