Jenkins "checkout scm" Failed - Fix SCM Checkout in Pipelines

By Daniel Zoghalchali·Latchkey

checkout scm re-checks-out the same repo/revision the Jenkinsfile came from. It fails when that revision no longer exists (force-push), a shallow clone cannot find the ref, submodules fail, or the SCM credential cannot authenticate.

What this error means

A multibranch/pipeline build fails at checkout scm with a Git error - couldn't find remote ref, a failed submodule update, or an auth error - even though the rest of the Jenkinsfile is unchanged.

Jenkins console

Checking out Revision 9af1c2e (refs/remotes/origin/PR-42)
ERROR: Couldn't find any revision to build. Verify the repository and branch
configuration for this job.
# or
fatal: reference is not a tree: 9af1c2e...

Diagnose it: agent, workspace, or sandbox?

Declarative pipeline failures usually come from the environment rather than the script: no matching agent, a dirty reused workspace, or the Groovy sandbox rejecting a method.

Jenkinsfile

// print what the agent actually is
sh 'hostname && whoami && pwd && java -version'
sh 'env | sort | head -40'

// workspaces are REUSED between builds by default
cleanWs()

Common causes

The recorded revision no longer exists

A force-push or branch deletion removed the commit the build expected, so checkout scm cannot resolve the revision it was told to build.

Shallow clone or refspec misses the ref

A shallow clone (small depth) or a narrow refspec does not fetch the needed commit/tag, so the checkout cannot find the revision.

Submodule or credential failure

A private submodule with no credential, or an expired SCM token, makes the checkout (or submodule update) fail to authenticate.

How to fix it

Re-scan/rebuild against an existing revision

Re-scan the multibranch project so Jenkins picks up the current head after a force-push.
Build the branch fresh so it resolves a revision that still exists.
If you pin a commit, ensure it has not been removed from the remote.

Fetch enough history and handle submodules/auth

Increase clone depth or fetch tags, and configure submodule credentials explicitly via checkout.

Jenkinsfile

checkout([$class: 'GitSCM',
  branches: scm.branches,
  userRemoteConfigs: scm.userRemoteConfigs,
  extensions: [
    [$class: 'CloneOption', shallow: false, depth: 0, noTags: false],
    [$class: 'SubmoduleOption', recursiveSubmodules: true,
     parentCredentials: true]
  ]
])

How to prevent it

Avoid force-pushing branches that have in-flight builds.
Use sufficient clone depth (or full clone) when builds need history/tags.
Configure submodule and SCM credentials so checkout authenticates cleanly.

Frequently asked questions

What causes Jenkins "checkout scm" failed?

There are 3 common causes: the recorded revision no longer exists, shallow clone or refspec misses the ref, and submodule or credential failure. A force-push or branch deletion removed the commit the build expected, so checkout scm cannot resolve the revision it was told to build.

How do I fix Jenkins "checkout scm" failed?

There are 2 fixes depending on which cause you have: re-scan/rebuild against an existing revision and fetch enough history and handle submodules/auth. Work through them in order, since the first is the most common.

What does Jenkins "checkout scm" failed actually mean?

A multibranch/pipeline build fails at checkout scm with a Git error - couldn't find remote ref, a failed submodule update, or an auth error - even though the rest of the Jenkinsfile is unchanged.

How do I stop Jenkins "checkout scm" failed happening again?

Avoid force-pushing branches that have in-flight builds. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation