How to fix Out of Shared Memory in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 99 views

Terraform encounters shared memory exhaustion, typically in Terraform Enterprise with PostgreSQL backends. This occurs when the system's IPC shared memory is insufficient for the database operations.

Quick fix

Fixes Out of Shared Memory

SHOW shared_buffers;
SHOW max_locks_per_transaction;
SHOW dynamic_shared_memory_type;
  1. Check current PostgreSQL shared memory settings
  2. Increase PostgreSQL shared_buffers parameter
  3. Increase max_locks_per_transaction
  4. Increase Docker shared memory size (if using Docker)
terraform — error
SHOW shared_buffers;
SHOW max_locks_per_transaction;
SHOW dynamic_shared_memory_type;
Out of Shared Memory

What this error means

The 'Out of Shared Memory' error indicates that PostgreSQL (used by Terraform Enterprise) cannot allocate enough Inter-Process Communication (IPC) shared memory for its operations. Shared memory is a kernel resource used by PostgreSQL for buffer pools, locks, and process coordination. When this limit is exceeded, the database cannot function properly and Terraform operations fail.

Typical symptoms

  • Terraform Enterprise becomes unresponsive or crashes
  • PostgreSQL logs contain 'could not resize shared memory segment' errors
  • Terraform apply or plan operations fail mid-execution
  • Database operations slow down significantly before failure
  • Error appears in Terraform Enterprise in mounted disk (FDO) deployments

Common causes

  1. PostgreSQL shared_buffers parameter set too low (default 128MB is insufficient for production)
  2. max_locks_per_transaction set below required threshold (default 64)
  3. Docker's default shared memory size (/dev/shm) too small at 64MB with posix dynamic_shared_memory_type
  4. High load environments with many concurrent Terraform operations
  5. Insufficient kernel IPC shared memory limits on the host system

How to fix "Out of Shared Memory"

1Check current PostgreSQL shared memory settings

Connect to your PostgreSQL database and verify current settings:

sql
SHOW shared_buffers;
SHOW max_locks_per_transaction;
SHOW dynamic_shared_memory_type;

For Terraform Enterprise, access the PostgreSQL container logs to identify the exact exhaustion point.

2Increase PostgreSQL shared_buffers parameter

Edit the postgresql.conf file (typically in the PostgreSQL data directory) and increase shared_buffers:

ini
shared_buffers = 512MB

For very high-load environments, consider 1024MB or higher. The rule of thumb is 25% of available system RAM, but PostgreSQL automatically adjusts if you specify too much.

For Terraform Enterprise on mounted disk, copy postgresql.conf from the container to the host mounted disk path and create a bind mount.

3Increase max_locks_per_transaction

In the same postgresql.conf file, increase max_locks_per_transaction:

ini
max_locks_per_transaction = 512

This determines how many locks each transaction can hold. High-concurrency environments may need 1024 or more.

4Increase Docker shared memory size (if using Docker)

If running Terraform Enterprise in Docker, increase the /dev/shm allocation in your docker-compose.yml:

yaml
services:
  tfe:
    shm_size: '1gb'

Restart the container after this change. This ensures dynamic_shared_memory_type = posix has sufficient space.

5Increase kernel IPC shared memory limits (if needed)

Check and increase kernel limits if PostgreSQL still fails:

bash
cat /proc/sys/kernel/shmmax
cat /proc/sys/kernel/shmall

To increase permanently, edit /etc/sysctl.conf:

ini
kernel.shmmax = 17179869184
kernel.shmall = 4194304

Apply changes:

bash
sudo sysctl -p
6Restart PostgreSQL and Terraform Enterprise

After configuration changes, restart PostgreSQL (or the entire TFE container):

bash
# For standalone PostgreSQL
sudo systemctl restart postgresql

# For Docker container
docker-compose restart tfe

Monitor the PostgreSQL logs to ensure no errors appear:

bash
tail -f /var/log/postgresql/postgresql.log
7Verify the fix with a test Terraform operation

Run a terraform plan or apply to verify the issue is resolved:

bash
terraform plan

The operation should complete without shared memory errors. Monitor system memory and PostgreSQL logs during execution to ensure stability.

Advanced notes

For extremely large configurations with hundreds of modules, consider splitting the Terraform workload into smaller units with separate state files. This reduces memory pressure on the PostgreSQL backend. Additionally, monitor memory consumption patterns over time—if memory grows unbounded, you may be experiencing the OOM Killer issue documented in HashiCorp support articles. In such cases, also check for unbounded memory growth in puma processes within the TFE container and consider resource limits or container memory constraints. For Terraform versions 1.6.0+, upgrade to benefit from optimized provider schema caching that significantly reduces memory consumption.

Frequently asked questions

What does "Out of Shared Memory" mean?
The 'Out of Shared Memory' error indicates that PostgreSQL (used by Terraform Enterprise) cannot allocate enough Inter-Process Communication (IPC) shared memory for its operations. Shared memory is a kernel resource used by PostgreSQL for buffer pools, locks, and process coordination. When this limit is exceeded, the database cannot function properly and Terraform operations fail.
How do I fix "Out of Shared Memory"?
Terraform encounters shared memory exhaustion, typically in Terraform Enterprise with PostgreSQL backends. This occurs when the system's IPC shared memory is insufficient for the database operations.
What causes "Out of Shared Memory"?
PostgreSQL shared_buffers parameter set too low (default 128MB is insufficient for production) max_locks_per_transaction set below required threshold (default 64) Docker's default shared memory size (/dev/shm) too small at 64MB with posix dynamic_shared_memory_type
Is the "Out of Shared Memory" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading