GitLab CI Troubleshooting

Pipeline Failure: Insufficient Disk Space in apt Archives

Problem

Your GitLab CI pipeline fails with an error message similar to:

You don't have enough free space in /var/cache/apt/archives/

This error occurs when the GitLab runner’s Docker environment runs out of disk space in the apt package cache directory.

Solution

  1. Connect to the GitLab runner server 
    ssh root@gitlab-runner.ext.dev

    This connects you to the server hosting the GitLab runner with root privileges.

  2. Clean up Docker volumes 
    docker volume prune -f

    This command removes all unused Docker volumes to free up disk space.

What These Commands Do

  • SSH connection: Establishes a secure shell connection to the GitLab runner server where the CI/CD jobs are executed
  • Docker volume prune: Removes all Docker volumes that are not currently used by any containers
    • The -f flag forces the operation without asking for confirmation
    • This frees up disk space by removing cached data, temporary files, and unused volumes

Prevention

Consider setting up automated cleanup jobs or monitoring disk usage on the runner server to prevent this issue from recurring.