🚨 Jenkins Error: 'ERROR: Maximum checkout retry attempts reached, aborting' — Cause, Fix, and Troubleshooting Guide

Overview

The Jenkins Git plugin retries a failed git fetch/git checkout a fixed number of times before it gives up. When every attempt fails, the build stops with:

ERROR: Maximum checkout retry attempts reached, aborting

This is the plugin exhausting its retryCount — the underlying Git command failed repeatedly. The retry line hides the real error (a transport failure, timeout, auth rejection, or a repo too big to clone in the allotted time), so the fix is to surface the underlying git failure and then address it rather than simply raising the retry count.

Symptoms

• The build console ends with Maximum checkout retry attempts reached, aborting after several Retrying after 10 seconds lines.
• Each retry logs the same underlying error just above it (for example Could not read from remote repository, Connection timed out, or RPC failed; curl transfer closed).
• Failures are intermittent — the same job succeeds on a re-run, pointing at a flaky network or SCM.
• Large repositories, repos with Git LFS, or repos with submodules fail more often than small ones.
• Failures cluster on specific agents (agent-01) while other agents on the same job succeed.
• The SCM server (self-hosted GitLab/Gitea/Bitbucket) shows elevated load or a maintenance window at the failure times.

Common Root Causes

• Flaky network path to the SCM — transient DNS, packet loss, proxy hiccups, or an overloaded Git server cause git fetch to fail; the retry helps only if the glitch clears within the retry window.
• Checkout timeout too low for a large repo — the default clone/fetch timeout (10 minutes) is not enough for a multi-GB repository, so every attempt times out and burns a retry.
• Git LFS or submodules failing — LFS smudge downloads or --recurse-submodules hit a second endpoint (LFS store, submodule host) that is missing credentials or is unreachable, so the checkout never completes.
• Bad or missing credentials — the referenced <credentials-id> is wrong, expired, or lacks read access; each attempt fails auth and the retry cannot recover.
• Host key / SSH verification failure — the agent has no known host entry for the SCM, so every SSH attempt is rejected before it can transfer.
• No shallow/reference clone on a huge history — a full deep clone of a large-history monorepo repeatedly exhausts the timeout when a shallow or reference/mirror clone would finish instantly.

How to diagnose

Read the console output above the retry line — the real failure is logged on each attempt. In the classic UI open the build, then Console Output; in Blue Ocean expand the Checkout step.

Confirm the effective retry and timeout the job is using. In a declarative pipeline these come from the checkout/git step options; check the Jenkinsfile and the job’s SCM config in Configure → Source Code Management.

Reproduce the underlying Git command on the failing agent to see the true error, using the same credentials context:

# On agent-01, as the Jenkins agent user, against the same remote
git clone --verbose git@jenkins.example.com:team/big-repo.git /tmp/checkout-test
GIT_TRACE=1 GIT_CURL_VERBOSE=1 git fetch origin

Check the agent can resolve and reach the SCM host and that SSH host keys are known:

ping -c 3 jenkins.example.com
ssh -T git@jenkins.example.com          # verifies host key + credentials
git ls-remote git@jenkins.example.com:team/big-repo.git

Inspect the agent log for the plugin’s per-attempt detail (Manage Jenkins → System Log, or the agent’s remoting log), and time a full clone to see whether you are near the timeout:

time git clone --mirror git@jenkins.example.com:team/big-repo.git /tmp/mirror-test

Fixes

1. Raise the checkout timeout (and keep a sane retry count)

Most large-repo failures are timeouts, not network flaps. Add the CheckoutOption and CloneOption extensions with a longer timeout instead of just increasing retries:

checkout([
  $class: 'GitSCM',
  branches: [[name: '*/main']],
  userRemoteConfigs: [[
    url: 'git@jenkins.example.com:team/big-repo.git',
    credentialsId: '<credentials-id>'
  ]],
  extensions: [
    [$class: 'CheckoutOption', timeout: 30],          // minutes
    [$class: 'CloneOption', timeout: 30, depth: 0, noTags: false, shallow: false]
  ]
])

The global retry count lives in Manage Jenkins → System → Git plugin → Global Config → “Git clone retry count”; raising it from 3 to 5 only helps for genuinely transient faults.

2. Use a shallow clone / reference repo for large history

Cut transfer time so a clone finishes well inside the timeout:

checkout([
  $class: 'GitSCM',
  branches: [[name: '*/main']],
  userRemoteConfigs: [[url: 'git@jenkins.example.com:team/big-repo.git',
                       credentialsId: '<credentials-id>']],
  extensions: [
    [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 20],
    // Or reuse a pre-seeded mirror on the agent to avoid re-downloading:
    [$class: 'CloneOption', reference: '/var/lib/jenkins/git-cache/big-repo.git']
  ]
])

Seed the reference mirror once per agent (git clone --mirror … /var/lib/jenkins/git-cache/big-repo.git) and refresh it on a schedule.

3. Handle LFS and submodules explicitly

If the repo uses LFS or submodules, the second endpoint needs credentials and time of its own:

extensions: [
  [$class: 'GitLFSPull'],
  [$class: 'SubmoduleOption',
     recursiveSubmodules: true,
     parentCredentials: true,      // reuse the parent repo credentials
     timeout: 30]
]

parentCredentials: true is the common fix for submodules that clone anonymously and get rejected.

4. Fix credentials and SSH host keys

If the underlying error is auth or host-key related, retrying will never help. Confirm the <credentials-id> exists and has read access, and make host-key verification deterministic in Manage Jenkins → Security → Git Host Key Verification Configuration (use “Manually provided keys” or “Known hosts file” rather than “No verification” in production). See the sibling guides below.

5. Add a scoped pipeline-level retry as a safety net

For truly transient SCM blips, wrap just the checkout so a one-off failure recovers without re-running the whole build:

stage('Checkout') {
  steps {
    retry(2) {
      timeout(time: 30, unit: 'MINUTES') {
        checkout scm
      }
    }
  }
}

What to watch out for

• Don’t fix this by only bumping the retry count — if the root cause is auth, a bad host key, or a timeout, more retries just make the job fail slower.
• Reference/mirror caches must be refreshed; a stale mirror can force a large delta fetch that reintroduces the timeout.
• Shallow clones break tools that need full history (some versioning plugins, git describe against old tags) — verify your build steps still work.
• LFS-enabled agents need the git-lfs binary installed; without it the smudge filter fails on every attempt.
• Monitor SCM server health — a repeatedly overloaded Git server will exhaust retries fleet-wide. For a live diagnosis of a stuck build, the free incident assistant at /dashboard/incident-response/ can help triage the underlying Git error.

Related

• Jenkins Error: ‘hudson.plugins.git.GitException: Command “git …” returned status code 128’ — the underlying Git command failure the retry is hiding.
• Jenkins Error: ‘Host key verification failed’ — when the retries are all failing on SSH host-key rejection.
• GitLab CI Error: ‘Could not resolve host’ — the DNS-side variant of an unreachable SCM.