Build chain fails: artifact dependency on '.teamcity/settings/digest.txt' is missing for some upstream builds

Symptoms

A TeamCity build chain is configured with an artifact dependency that targets .teamcity/settings/digest.txt, typically as a small placeholder file used to pin a specific upstream build version without downloading large artifacts. For some upstream builds, the file is not produced, and downstream builds fail with Failed to resolve artifact dependency error.

This pattern most often appears when snapshot dependencies do not expose the required build-version selector, and digest.txt is used as a surrogate to enforce version pinning across the chain.

Cause

.teamcity/settings/digest.txt is part of TeamCity's hidden artifacts, stored under the .teamcity directory in the build's artifact root. Hidden artifacts are generated for internal TeamCity purposes — build-equivalence checks for snapshot dependency reuse, parameter propagation through chains, and similar mechanisms.

Key properties of hidden artifacts:

• Artifact dependencies do not consider hidden artifacts unless the dependency pattern explicitly specifies .teamcity.
• Hidden artifacts are not removed by default cleanup, but can be deleted when .teamcity is included in the cleanup scope at the project or build configuration level.
• The contents and presence of these files are not contractual. They may differ between TeamCity versions and may be absent in edge cases, for example, when a build is canceled or interrupted before the settings freeze completes.

The settings digest itself is computed from the merged default and custom settings of the build. Two builds with the same default settings can produce different digests if their customizations differ. Background discussion: TW-78836.

Because hidden artifacts are intended for internal use, they do not follow any public change policy and can change or disappear without notice.

Resolution

Replace the artifact dependency on digest.txt with a regular artifact produced by the upstream build, combined with an appropriate revision rule on the dependency.

1. Publish a regular version artifact from the upstream build

In each upstream build that downstream builds depend on, write a small file containing a version identifier (commit SHA, semantic version, build-specific digest, or any value relevant to the dependency contract). Add an artifact path rule on the upstream build configuration:

version.txt => version.txt

The build script must produce version.txt before TeamCity collects artifacts. Because the file is published as a regular (non-hidden) artifact, its presence is controlled by the build script and is not subject to changes in TeamCity internals.

2. Configure the artifact dependency with a revision rule

On the downstream build configuration, declare an artifact dependency on version.txt and choose a revision rule that matches the intended version-pinning behavior:

The full list of revision-rule options and configuration steps is documented in Artifact Dependencies.