TeamCity "Failed to start build" due to a VCS root error in CI

By Daniel Zoghalchali·Latchkey

The build was assigned to an agent but could not start because the VCS root failed during checkout: unreachable remote, bad credentials, or an unresolvable revision. The build ends immediately without running steps.

What this error means

The build fails at the very start with "Failed to start build" and a VCS-related detail such as "Failed to perform checkout" or a revision that cannot be resolved.

Failed to start build: Failed to perform checkout on agent for VCS root "app":
Cannot resolve revision 'refs/heads/feature-x'

Common causes

The requested revision no longer exists

A branch was deleted or force-pushed, so the revision the build was queued against cannot be checked out.

The VCS root is unreachable or unauthenticated at checkout

Network, credential, or URL problems that pass polling can still fail at checkout time on the agent.

How to fix it

Re-queue against a valid revision

1. Confirm the branch and commit still exist in the repository.
2. If a branch was deleted or rewritten, trigger a fresh build so it picks a current revision.
3. Verify the VCS root "Test connection" succeeds from the server.

Fix agent-side VCS access

Ensure the agent can reach the repository host and that Git (or the bundled VCS) is available and authenticated on the agent.

How to prevent it

• Avoid force-pushing branches with builds queued against them.
• Keep VCS credentials and network reachable from agents, not just the server.
• Use "Test connection" after VCS root changes.

Frequently asked questions

Related guides

References

• GitHub Actions documentation