Introduction

The error INTERNAL ERROR: cannot create temporary directory from docker-compose means the system cannot create files in the temporary directory (typically /tmp on Linux or the path specified by the TMPDIR environment variable). This usually indicates a disk space issue, permission problem, or filesystem being mounted as read-only.

The Error

The full error message typically appears as:

INTERNAL ERROR: cannot create temporary directory!

This can occur when running any docker-compose command (up, build, pull, etc.).

Common Causes and Fixes

1. Disk Full (Most Common)

The /tmp directory or the filesystem it resides on is out of space:

1# Check disk usage
2df -h /tmp
3df -h /
4
5# Check what's consuming space in /tmp
6du -sh /tmp/* | sort -rh | head -20

Fix by freeing space:

1# Remove old temporary files
2sudo rm -rf /tmp/docker-*
3sudo rm -rf /tmp/pip-*
4
5# Clean Docker resources
6docker system prune -f
7docker volume prune -f
8docker image prune -a -f
9
10# Check space again
11df -h /

2. Permission Issues

Your user does not have write permission to the temp directory:

1# Check permissions
2ls -la /tmp
3
4# /tmp should have permission 1777 (sticky bit)
5# drwxrwxrwt
6
7# Fix permissions if wrong
8sudo chmod 1777 /tmp

3. /tmp Mounted as Read-Only

On some systems or containers, /tmp may be mounted read-only:

1# Check if /tmp is read-only
2mount | grep /tmp
3
4# Test write access
5touch /tmp/test_write && rm /tmp/test_write

If read-only, remount or set a different temp directory:

1# Remount /tmp as read-write
2sudo mount -o remount,rw /tmp
3
4# Or use a different temp directory
5export TMPDIR=/var/tmp
6docker-compose up

4. noexec Flag on /tmp

Some security-hardened systems mount /tmp with noexec, which can cause issues:

1# Check mount options
2mount | grep /tmp
3# If you see "noexec": tmpfs on /tmp type tmpfs (rw,nosuid,nodev,noexec)
4
5# Remount without noexec
6sudo mount -o remount,exec /tmp

5. Docker Compose Running in a Restricted Container

If docker-compose itself is running inside a container (CI/CD pipelines), the container's /tmp may be restricted:

1# docker-compose.yml for CI
2services:
3  ci-runner:
4    volumes:
5      - /tmp:/tmp  # Mount host's /tmp
6    environment:
7      - TMPDIR=/tmp

Or in a Dockerfile:

RUN mkdir -p /app/tmp && chmod 777 /app/tmp
ENV TMPDIR=/app/tmp

Changing the Temporary Directory

If you cannot fix /tmp, tell docker-compose to use a different location:

1# Set a custom temp directory
2export TMPDIR=$HOME/tmp
3mkdir -p $TMPDIR
4
5# Now run docker-compose
6docker-compose up -d

For a permanent fix, add to your shell profile:

# ~/.bashrc or ~/.zshrc
export TMPDIR=$HOME/tmp
mkdir -p $TMPDIR

CI/CD Pipeline Fix

This error is common in CI/CD environments where runners have limited disk space:

GitHub Actions

1- name: Free disk space
2  run: |
3    docker system prune -af
4    sudo rm -rf /tmp/*
5    df -h /tmp
6
7- name: Start services
8  run: docker-compose up -d

GitLab CI

1before_script:
2  - docker system prune -f
3  - df -h /tmp
4  - export TMPDIR=/builds/tmp && mkdir -p $TMPDIR

Preventive Measures

Set up automatic cleanup of the temp directory to avoid this error recurring:

# Cron job to clean old temp files daily
# Add to crontab: crontab -e
0 2 * * * find /tmp -type f -atime +7 -delete 2>/dev/null

For Docker specifically:

# Schedule Docker cleanup
0 3 * * * docker system prune -f --filter "until=72h" 2>/dev/null

Common Pitfalls

• Cleaning /tmp blindly: Other applications use /tmp too. Only remove files you can identify (docker-, pip-, etc.) rather than running rm -rf /tmp/* which could break running processes.
• Docker overlay2 growth: Docker's storage driver (overlay2) can fill the disk. Check /var/lib/docker/overlay2 size and prune unused images/containers.
• Inode exhaustion: Even with free disk space, you can run out of inodes, preventing new file creation. Check with df -i /tmp.
• Snap-installed Docker: On Ubuntu, snap-installed Docker may have restricted /tmp access. Use the apt-installed version instead.
• SELinux / AppArmor: Security modules can deny write access to /tmp for Docker processes. Check journalctl -xe for SELinux or AppArmor denials.

Summary

• This error almost always means the temp directory is full or not writable
• Check disk space first with df -h /tmp and df -h /
• Free space with docker system prune and by clearing old temp files
• Set TMPDIR to an alternative directory if /tmp cannot be fixed
• In CI/CD, add disk cleanup steps before docker-compose commands