Bamboo "The plan failed to checkout" in CI

The Source Code Checkout task ran but could not produce a clean working copy at the requested revision. Bad credentials, a missing branch, or a corrupted or locked workspace usually causes it.

What this error means

The build fails during the checkout task with "The plan failed to checkout" or "Checkout of the repository failed", before any build script runs.

Bamboo

The plan failed to checkout the source code.
Updating source code to revision ... failed: reference 'refs/heads/feature-x' not found.

Common causes

The target branch or revision no longer exists

The plan branch was deleted or the revision was force-pushed away, so the checkout task cannot resolve the ref.

A stale or locked agent workspace

A previous build left a corrupted or lock-held working copy, so the update cannot proceed and the checkout fails.

How to fix it

Force a clean checkout

Enable "Force clean build" (or clean the working directory) for the checkout task so a fresh working copy is fetched.
Re-run the build so the agent re-clones instead of updating a broken copy.
Confirm the branch and revision the plan targets still exist.

Bamboo administration

# Job > Checkout task > enable "Force Clean Build"
# or clear the agent working directory for the plan before re-running

Point the plan at an existing ref

If the branch was removed, update the plan or plan branch to a branch that still exists in the repository.

How to prevent it

Enable clean checkout for plans prone to leftover workspace state.
Avoid force-pushing away revisions a queued build is targeting.
Remove plan branches when their source branch is deleted.