Hidden Artifacts from .teamcity Consuming Excess Disk Space in TeamCity Cloud

Problem

Hidden artifacts within the .teamcity.build_cache folder are consuming excessive disk space in TeamCity, even for builds that appear older than the configured cleanup rules.

Cause [Optional]

This situation typically occurs when the cleanup conditions are not actually met, even though the builds appear old relative to the current date.

Potential causes include:

• The build is the latest build in its branch, so cleanup rules based on "older than the last build" are not triggered.
• Builds being pinned, which excludes them from cleanup operations.
• Cleanup rules at the project or parent project level overriding existing settings.
• Branch-based cleanup behavior, where rules are evaluated per branch rather than globally.
• Artifact dependencies protecting artifacts from deletion.
• The scheduled cleanup process not running or not completing successfully.

Resolution

1. Confirm Pin Status

   • Verify whether the build is pinned, as pinned builds are excluded from the cleanup process.
   • Reference documentation on pinned builds:
     TeamCity Build Actions - Pin Build.

2. Verify Branch-Based Cleanup Behavior

   • TeamCity evaluates rules such as "Artifacts more than N days older than the last build" relative to the last build in the same branch, not relative to the current date.
   • If the affected build is the latest build in its branch, it will be considered 0 days older than the last build, and cleanup rules will not apply.
   • This commonly occurs with long-lived feature branches that no longer receive builds.

3. Review Cleanup Rules

   • Ensure cleanup rules are correctly configured and active at the project level.
   • Confirm they are not overridden by rules inherited from a parent project.
   • Review documentation:
     TeamCity Data Cleanup.

4. Evaluate Inherited Rules

   • Confirm whether the project inherits rules from the root project.
   • Check whether base rules or keep rules at higher levels prevent artifact removal.

5. Check Artifact Dependency Protection

   • Artifacts may be preserved if they are referenced by artifact dependencies in other builds.
   • The option "Do not prevent dependency artifacts cleanup" can affect this behavior, but dependencies may still protect artifacts in some scenarios.

6. Assess Cleanup Execution

   • Verify that the cleanup process runs periodically and completes successfully.
   • In TeamCity Cloud, cleanup typically runs automatically but may take time depending on instance load.

7. Enable Cleanup Diagnostics

   • Add the tag diagnostics:cleanup to one or more builds where artifacts should have already been removed.

   • Wait for the next cleanup run (or trigger one manually if available in TeamCity Cloud).

   • A diagnostic report will be generated under:

     .teamcity/cleanup/
     

   • This report explains which cleanup rule, keep rule, dependency, or pin condition prevented deletion.

8. Consider Additional Cleanup Rules

   To avoid large caches accumulating in feature branches:

   • Add rules to limit the number of builds per branch.
   • Configure cleanup for inactive branches.
   • Review whether .teamcity.build_cache artifacts need to be retained long-term.

9. Provide Examples

   • Collect several build examples where .teamcity.build_cache artifacts remain despite cleanup expectations.
   • Include build links, branch names, and artifact details to assist with further investigation.

Note

Hidden artifacts in .teamcity.build_cache (such as Gradle cache archives) can grow very large. If cleanup rules rely on "older than last build", these artifacts may remain indefinitely for branches that no longer receive new builds. Configuring cleanup rules for inactive branches or limiting builds per branch can help prevent long-term storage growth.