TeamCity agent "free disk space is below threshold" in CI

TeamCity checks free disk space on the agent before and during a build. When it drops below the configured "free-space-required" threshold, the agent is treated as unable to run the build, or the running build is failed.

What this error means

The build fails or the agent goes unavailable with "Agent has less than N MB of free disk space" or "Free disk space requirement is not met". The agent work and temp directories are usually full.

Failed to start build: Agent "Agent-1" has less than 3000 MB of free disk space.
Free disk space on the agent is below the required threshold.

Common causes

Accumulated checkout, work, and temp directories

Old checkout directories, build outputs, and Docker layers pile up under the agent work and temp folders until free space falls below the threshold.

A free-space requirement larger than available disk

The teamcity.agent.ensure.free.space build feature or configuration demands more free space than the agent host provides.

How to fix it

Free space by cleaning agent directories

1. Enable the Swabra build feature (clean checkout / clean-up) on the build configuration.
2. Delete stale checkout directories under <agent>/work and temp files under <agent>/temp.
3. Prune unused Docker images and volumes on the agent host if it builds containers.

# on the agent host, reclaim space used by images/containers
docker system prune -af

Set a realistic free-space requirement

Use the "Free disk space" build feature with a threshold the host can meet, or add disk to the agent so the requirement passes.

# require free space via build parameter (agent side)
teamcity.agent.ensure.free.space=3gb

How to prevent it

• Enable Swabra to clean checkout directories between builds.
• Provision agent disks with headroom above the free-space requirement.
• Prune Docker and build caches on agents on a schedule.

Related guides