Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

PostgreSQL cluster fails to start with pg_ctlcluster on Ubuntu or Debian

ErrorFailed to start PostgreSQL Cluster 16-main.

Short answer

The systemd message only says the cluster did not start; the reason is in the cluster's own log. Read /var/log/postgresql, or start the cluster in the foreground to see the error on screen. Then fix what it names: a port already in use, data directory permissions, or shared memory and semaphore limits.

  • Applies to PostgreSQL 16, PostgreSQL 17, Ubuntu 24.04, Debian 12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Show the clusters (version, name, port, data directory), then print the end of the log of the failing one. Replace 16-main with your cluster.

    pg_lsclusters
    sudo tail -n 30 /var/log/postgresql/postgresql-16-main.log
  2. 2Match what you see, then jump to its fix

    1. 1could not bind IPv4 address ...: Address already in useAnother process already holds the portFix
    2. 2The log complains about the data directory, usually after a restore, copy or mount changeData directory permissions are wrongFix
    3. 3could not create shared memory segment: Invalid argument, or could not create semaphores: No space left on deviceKernel limits for shared memory or semaphoresFix

What does the error look like?

  • Failed to start PostgreSQL Cluster 16-main.
  • could not bind IPv4 address "127.0.0.1": Address already in use
  • FATAL: could not create any TCP/IP sockets

Cause 1 of 3

Another process already holds the port

1Check

Two clusters, or a manually started server, may use the same port. Find who listens on 5432.

sudo ss -ltnp | grep 5432

2Fix

Stop the other server, or give this cluster a different port in its postgresql.conf, then start it.

sudo grep -n "^port" /etc/postgresql/16/main/postgresql.conf
sudo pg_ctlcluster 16 main start

3Verify

The status command reports a running server.

sudo pg_ctlcluster 16 main status

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 3

Data directory permissions are wrong

1Check

A cluster data directory must be owned by the PostgreSQL user and closed to everyone else. The expected modes are 0700 for directories and 0600 for files, or 0750 and 0640 when group read is allowed.

sudo ls -ld /var/lib/postgresql/16/main

2Fix

Give the directory back to the postgres user and set the mode while the cluster is stopped.

sudo chown -R postgres:postgres /var/lib/postgresql/16/main
sudo chmod 0700 /var/lib/postgresql/16/main
sudo pg_ctlcluster 16 main start

3Verify

The status command reports a running server.

sudo pg_ctlcluster 16 main status

Confirmed by postgresql.org

Did this fix it?

Cause 3 of 3

Kernel limits for shared memory or semaphores

1Check

The second message does not mean the disk is full. It means the System V semaphore limit is below what PostgreSQL asks for. The shared memory message applies when shared_memory_type is sysv.

sudo grep -n "shared_buffers\|max_connections\|shared_memory_type" /etc/postgresql/16/main/postgresql.conf

2Fix

Start with fewer buffers or fewer connections, and raise the kernel limit for the long term.

# in postgresql.conf, then start the cluster again
max_connections = 50
shared_buffers = 128MB

3Verify

The cluster starts and the log has no FATAL line.

sudo tail -n 5 /var/log/postgresql/postgresql-16-main.log

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Run pg_lsclusters after every package upgrade to see which clusters exist and which ports they use.
  • Do not copy a data directory without keeping its owner and mode.
  • Keep one server per port and never start a second postgres by hand on a managed cluster.

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.