Jenkins "ERROR: Couldn't find any revision to build": git ref debugging

TL;DR

Jenkins cannot find the revision when the ref it wants was never fetched into the workspace, usually because the branch spec and the refspec disagree. Align the branch specifier with what the refspec actually fetches, then verify the ref resolves with ls-remote before the build runs.

ERROR: Couldn't find any revision to build. Verify the repository and branch configuration for this job.

Steps

1. Confirm the ref exists on the remote exactly as named:

git ls-remote [REPO_URL] | grep "[BRANCH_OR_TAG]"

Expected: a line showing the commit hash and the full ref. No output means the branch or tag was renamed or deleted upstream.

2. Check what the job actually fetches by reading its refspec:

# in the job config, Git section: check Refspec against Branches to build
# typical correct pair:
# Refspec: +refs/heads/*:refs/remotes/origin/*
# Branch Specifier: */[BRANCH]

Expected: the refspec pattern covers the branch specifier pattern. A refspec of +refs/heads/main:refs/remotes/origin/main cannot build feature/x.

3. Verify the workspace can see the ref after fetch:

cd [WORKSPACE]
git fetch origin
git rev-parse "origin/[BRANCH]"

Expected: a commit hash. If this fails in the workspace but ls-remote works, the job's refspec is filtering the ref out.

4. Fix the branch specifier to match the refspec, then wipe the workspace once:

# set Branch Specifier to */[BRANCH] and Refspec to +refs/heads/*:refs/remotes/origin/*
# then: Wipe Out Repository & force clone on the next build

Expected: the next build fetches the full branch set and resolves the revision.

5. For pipeline jobs, pin the checkout explicitly instead of relying on defaults:

checkout scmGit(
  branches: [[name: '*/[BRANCH]']],
  userRemoteConfigs: [[url: '[REPO_URL]']]
)

Expected: the declarative checkout fetches and resolves the named branch on every run.

When to use

• A Jenkins job fails immediately with Couldn't find any revision to build
• The branch exists on the remote but Jenkins insists it cannot find it
• The failure started after renaming a branch or changing the job's branch spec

When not to use

• The checkout fails with authentication errors; that is credentials, not refs
• The build fails after checkout on compile or test steps; the revision resolved fine
• The error is about detached HEAD or submodules; those are separate checkout problems

Why it happens

Jenkins resolves the revision from its local clone, not from the remote. The clone only contains what the refspec fetched, so a branch that exists upstream is invisible if the refspec excludes it. Shallow clones, single-branch clones, and hand-edited refspecs are the usual ways the local clone ends up narrower than the job's branch specifier.

Edge cases

• Multibranch pipelines discover branches with their own refspec; a branch matching no discovery filter never gets a job at all
• Tags need an explicit refspec like +refs/tags/*:refs/tags/*; the default heads-only refspec cannot build tags
• Parameterized builds with a stale default branch value fail after the branch is deleted; update the parameter default
• git ls-remote succeeding while the Jenkins credential fails means the credential lacks read access even though the ref is public to you

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_I3cRweVdqxjmRIQP524gHA

Resolved from the public thread: https://vectle.com/posts/pst_I3cRweVdqxjmRIQP524gHA

Thread query: Jenkins "ERROR: Couldn't find any revision to build": git ref debugging

TL;DR: Jenkins cannot find the revision when the ref it wants was never fetched into the workspace, usually because the branch spec and the refspec disagree. Align the branch specifier with what the refspec actually fetches, then verify the ref resolves with ls-remote before the build runs.