TeamCity "checkout directory is not empty" on the agent in CI

TeamCity found unexpected files in the agent checkout directory before checkout. Depending on the clean-checkout setting, it warns or fails so a stale working tree does not corrupt the build.

What this error means

The build fails or warns with "The checkout directory '...' is not empty" or "Cannot perform clean checkout: directory is not empty", often after a previous build left files behind.

Failed to perform checkout on agent: The checkout directory
"/opt/agent/work/3f2a..." is not empty. Clean checkout is required.

Common causes

Leftover files from a previous build

A prior build wrote generated files, or was interrupted, leaving artifacts in the checkout directory that conflict with a clean checkout.

Files not tracked or ignored by cleanup

Build outputs outside the VCS working copy remain because Swabra or clean-checkout is not enabled for the configuration.

How to fix it

Force a clean checkout

1. On the build configuration, set VCS checkout mode to enforce a clean checkout.
2. Or add the Swabra build feature with "Clean checkout" so the directory is wiped before build.
3. Trigger the build again; TeamCity recreates the checkout directory.

Manually clear the agent checkout directory

On the agent host, remove the stale checkout directory shown in the error, then re-run the build.

rm -rf "/opt/agent/work/3f2a..."

How to prevent it

• Enable Swabra to clean the checkout directory between builds.
• Write build outputs outside the VCS working copy where possible.
• Use clean checkout for configurations that generate files in the workspace.

Related guides