Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

A Postgres query in Docker fails with: could not resize shared memory segment

Errorpq: could not resize shared memory segment "/PostgreSQL.1234567890" to 67145856 bytes: No space left on device

Short answer

Postgres in a container hands query memory to parallel workers through the container's /dev/shm. When that area is too small, a heavy query fails with this error even though the disk is not full. Give the service a larger shm_size, or make the query use less memory.

  • Applies to postgres Docker image 17, Docker Engine 28, Docker Compose 2, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the size of /dev/shm inside the running container. A small value here, while the host disk has plenty of space, points to the first cause.

    docker compose exec db df -h /dev/shm
    docker compose exec db psql -U postgres -c "show work_mem;" -c "show max_parallel_workers_per_gather;"
  2. 2Match what you see, then jump to its fix

    1. 1df shows a small /dev/shm, and the error appears only on large joins, aggregations or dashboards.The container's /dev/shm is too smallFix
    2. 2Raising shm_size helps only for a while; the failing query is a hash join or a big GROUP BY.Parallel workers each take a full memory budgetFix

What does the error look like?

  • pq: could not resize shared memory segment "/PostgreSQL.1234567890" to 67145856 bytes: No space left on device
  • ERROR: could not resize shared memory segment: No space left on device

Cause 1 of 2

The container's /dev/shm is too small

1Check

On Linux, POSIX dynamic shared memory (the default type) is allocated with shm_open, and the container's shared memory area is /dev/shm. Compose sets its size per service with shm_size.

docker compose exec db df -h /dev/shm

2Fix

Set shm_size on the database service and recreate it (256mb is an example value; raise it if the error returns).

services:
  db:
    image: postgres:17
    shm_size: 256mb

3Verify

The new size shows in df and the failing query completes.

docker compose up -d
docker compose exec db df -h /dev/shm

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

Parallel workers each take a full memory budget

1Check

work_mem applies to every sort and hash table in a query and to each parallel worker separately, and hash operations may use work_mem multiplied by hash_mem_multiplier. A parallel query with 4 workers can use up to five times what a plain query uses.

show work_mem;
show hash_mem_multiplier;
show max_parallel_workers_per_gather;

2Fix

For the failing session, lower work_mem or turn parallel workers off, then tune the query or index instead.

SET work_mem = '16MB';
SET max_parallel_workers_per_gather = 0;

3Verify

Run the query again in the same session.

EXPLAIN (ANALYZE, BUFFERS) <your query>;

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Set shm_size in the compose file from the start instead of waiting for the first failure.
  • Keep work_mem modest globally; raise it per session for the few reports that need it.
  • For Swarm stacks, the Postgres image notes suggest a tmpfs mount at /dev/shm.
  • Check df -h /dev/shm whenever you move the database to a new orchestrator.

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.