The postgres container exits when ssl=on and a mounted certificate
Postgres unable to load ssl certificateShort answer
With ssl=on, PostgreSQL refuses to start if it cannot use the certificate and key. In a container that goes wrong in three ways: the files are not where the server looks, the key's owner or mode is wrong as the container sees it, or the key has a passphrase that nobody can type. Check the files from inside.
Fix it fast
1Find out which cause you have
Read the log of the failed start, then list the certificate files as the container sees them, with numeric owner IDs. A one-off container is used because the real one keeps exiting.
docker compose logs db --tail 20 docker compose run --rm --no-deps --entrypoint sh db -c "id postgres; ls -ln /certs"2Match what you see, then jump to its fix
- 1
The log names server.crt or server.key without a path, and your files are mounted somewhere elseThe server looks for server.crt and server.key in the data directoryFix - 2
The key is listed with a numeric owner that is not the postgres user, and a mode more open than 0600The key's owner or permissions are wrong inside the containerFix - 3
The container stops with no error about permissions, and the key file contains the word ENCRYPTEDThe private key is protected by a passphraseFix
- 1
What does the error look like?
Postgres unable to load ssl certificatethe container exits a second after docker compose up, and the log names server.crt or server.key
Cause 1 of 3
The server looks for server.crt and server.key in the data directory
1Check
By default PostgreSQL expects files called server.crt and server.key in its data directory. Other names and places have to be set with ssl_cert_file and ssl_key_file. Compare the volumes of the service with the paths the server is told to use.
docker compose config | grep -n -E "command:|ssl|/certs|volumes:"2Fix
Mount the files outside the data directory and pass the settings on the command line, which the image passes on to the server.
services:
db:
image: postgres:17
environment:
POSTGRES_PASSWORD: change-me-example
volumes:
- ./certs:/certs:ro
command: >
postgres
-c ssl=on
-c ssl_cert_file=/certs/server.crt
-c ssl_key_file=/certs/server.key3Verify
Start the stack and ask the server whether SSL is on.
docker compose up -d db
docker compose exec db psql -U postgres -c "SHOW ssl;"Confirmed by postgresql.org
Cause 2 of 3
The key's owner or permissions are wrong inside the container
1Check
On Unix, the key must disallow any access to group and world. That means mode 0600 owned by the user the server runs as, or owned by root with 0640 and the server user in that file's group. Compare the uid printed by id postgres with the owner and mode in the listing.
docker compose run --rm --no-deps --entrypoint sh db -c "id postgres; ls -ln /certs/server.key"2Fix
On a Linux host, give the key file to the ids that id postgres printed and set mode 0600. If the host cannot set the owner, build a small image for a test certificate with COPY --chown and --chmod; numeric ids need no user lookup during the build, and the ./certs mount is then not needed. Never push an image that holds a production key.
# on the Linux host, with the ids printed by id postgres
sudo chown <uid>:<gid> certs/server.key
chmod 600 certs/server.key
# or, for a test certificate only: Dockerfile
FROM postgres:17
COPY --chown=<uid>:<gid> --chmod=600 certs/server.key /certs/server.key
COPY certs/server.crt /certs/server.crt3Verify
The listing now shows the postgres ids and -rw-------, and the server starts.
docker compose run --rm --no-deps --entrypoint sh db -c "ls -ln /certs"Confirmed by docs.docker.com
Cause 3 of 3
The private key is protected by a passphrase
1Check
A key with a passphrase makes the server prompt for it, and it does not start until the passphrase is entered. A container has no one to type it.
grep -c ENCRYPTED certs/server.key2Fix
Create the key without a passphrase, as the manual's openssl example does with -nodes, or give the server a passphrase command through ssl_passphrase_command. For a local test certificate the manual's command is enough.
openssl req -new -x509 -days 365 -nodes -text -out certs/server.crt \
-keyout certs/server.key -subj "/CN=dbhost.example.com"
chmod og-rwx certs/server.key3Verify
Rebuild or restart the service. The log shows no prompt and the container stays up.
docker compose up -d --build db
docker compose ps dbConfirmed by postgresql.org
How do I stop it coming back?
- Keep certificate and key outside the data directory and name both files in -c options, so nothing depends on the default file names.
- Check the owner and mode of the key from inside the container whenever you change how it is delivered.
- Use a real certificate from your certificate authority in production; the openssl example is for tests.
- Remember that a bad file stops the server at start, while a bad file during a configuration reload is ignored and the old setting stays.
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
PostgreSQL will not start: permission denied on the SSL private key
FATAL: could not access private key file "/etc/ssl/private/ssl-cert-snakeoil.key": Permission denied
PostgreSQL only accepts a private key that nobody but the server can read.
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
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
EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
The query fails only after a delay, because the connection is retried several times
The transient failure message comes from EF Core's retry layer, which hides the underlying connection error.
3 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 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 fix