Articles

Fix Jenkins SCM Checkout Failures for Git and SVN (2026)

April 18, 2026 6 min read

Jenkins choked on pulling code from your Git or SVN repository, leaving you with a broken build. This isn’t just a minor hiccup; it means the core CI/CD pipeline is stuck, preventing any further progress until the source code can be reliably fetched.

Let’s break down why this happens and how to fix it, covering the most common culprits first.

Git Specific Failures

1. SSH Key Permissions or Missing Key

  • Diagnosis: On the Jenkins controller, check the permissions of the .ssh directory and the private key file. It should be 700 for .ssh and 600 for the private key. Also, ensure the key exists at the path specified in Jenkins’s SSH credentials.
    ls -ld ~/.ssh
ls -l ~/.ssh/id_rsa # or your specific key name
    In Jenkins, navigate to Manage Jenkins -> Credentials -> System -> Global credentials (or the specific domain you’re using) and verify the SSH Private Key credential is correct and its path points to a valid key file.
  • Fix:
    chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
    If the key is missing, generate a new one (ssh-keygen -t rsa -b 4096) and add the public key to your Git hosting service (GitHub, GitLab, Bitbucket).
  • Why it works: SSH requires strict file permissions to prevent unauthorized access to your private keys. If permissions are too loose, SSH will refuse to use the key for security reasons.

2. Git Credentials (HTTP/HTTPS) Incorrect or Expired

  • Diagnosis: In Jenkins, check the Username/Password credential used for the Git repository. Ensure the username and password (or personal access token) are still valid and have the necessary permissions on the Git server.
    # No direct command, but check Jenkins UI:
# Manage Jenkins -> Credentials -> System -> Global credentials
# Find your Git credential and click "Edit"
  • Fix: Update the username and password/token in the Jenkins credential entry. For services like GitHub, ensure you’re using a Personal Access Token (PAT) with appropriate scopes (e.g., repo) instead of your account password. If using a PAT, make sure it hasn’t expired.
  • Why it works: Jenkins uses these credentials to authenticate with the Git server. If they are wrong or expired, the server will reject the connection.

3. Git Client Not Installed or Not in PATH on Agent

  • Diagnosis: SSH into the Jenkins agent where the build is running and try to run git --version. If the command is not found, Git is not installed or not accessible in the agent’s PATH.
    ssh your-jenkins-agent-user@your-agent-hostname
git --version
  • Fix: Install Git on the agent machine. For Debian/Ubuntu: sudo apt-get update && sudo apt-get install git. For RHEL/CentOS: sudo yum install git. Ensure git is in the system’s PATH.
  • Why it works: Jenkins relies on the git executable being available on the system where it’s performing the checkout.

4. Repository URL Incorrect or Inaccessible

  • Diagnosis: Double-check the repository URL configured in the Jenkins job. Ensure it’s the exact URL for your Git repository, including the correct protocol (SSH or HTTPS). Try cloning the repository manually from the Jenkins agent machine using the same URL and credentials.
    # On the Jenkins agent
git clone <your-repository-url>
  • Fix: Correct the repository URL in the Jenkins job configuration. Ensure network connectivity from the Jenkins agent to the Git server (check firewalls, proxy settings).
  • Why it works: A malformed or unreachable URL means Jenkins can’t even find the repository to begin with.

5. Git Configuration Issues on Agent (e.g., user.name, user.email)

  • Diagnosis: Sometimes, Git operations can fail if user.name or user.email are not configured globally or locally on the agent, especially for certain Git commands that might be implicitly run by Jenkins plugins.
    # On the Jenkins agent
git config --global user.name
git config --global user.email
  • Fix: Configure Git with dummy values if the global configuration is missing or invalid, as Jenkins might be trying to perform operations that require these.
    # On the Jenkins agent
git config --global user.name "Jenkins CI"
git config --global user.email "jenkins-ci@example.com"
  • Why it works: While less common for simple checkouts, some Git operations triggered by Jenkins plugins might require basic Git configuration to be present on the agent to avoid errors.

SVN Specific Failures

1. Subversion Credentials Incorrect or Missing

  • Diagnosis: In Jenkins, check the Subversion credentials used for the repository. Verify the username and password are correct and have the necessary access rights to the SVN repository.
    # No direct command, but check Jenkins UI:
# Manage Jenkins -> Credentials -> System -> Global credentials
# Find your SVN credential and click "Edit"
  • Fix: Update the username and password in the Jenkins credential entry. If using SVN over HTTP/HTTPS, ensure the user has read permissions for the specified URL.
  • Why it works: Similar to Git, Jenkins needs valid credentials to authenticate with the SVN server.

2. Subversion Client (svn) Not Installed or Not in PATH on Agent

  • Diagnosis: SSH into the Jenkins agent and try to run svn --version. If the command is not found, the Subversion client is missing or not in the agent’s PATH.
    ssh your-jenkins-agent-user@your-agent-hostname
svn --version
  • Fix: Install the Subversion client on the agent machine. For Debian/Ubuntu: sudo apt-get update && sudo apt-get install subversion. For RHEL/CentOS: sudo yum install subversion. Ensure svn is in the system’s PATH.
  • Why it works: Jenkins needs the svn executable to interact with the Subversion repository.

3. Subversion Repository URL Incorrect or Inaccessible

  • Diagnosis: Verify the Subversion repository URL in the Jenkins job configuration. Ensure it’s the correct URL, including the correct protocol (svn, svn+ssh, http, https) and path. Try checking out the repository manually from the agent using the same URL.
    # On the Jenkins agent
svn checkout <your-repository-url>
  • Fix: Correct the repository URL in the Jenkins job configuration. Check network connectivity and firewall rules between the agent and the SVN server.
  • Why it works: An incorrect or unreachable URL prevents Jenkins from accessing the repository.

4. SVN Cache Corruption or Stale Information

  • Diagnosis: Sometimes, the SVN client on the agent can have corrupted cache data that interferes with checkout. This is harder to diagnose directly but often manifests as strange, seemingly random errors.
  • Fix: On the Jenkins agent, navigate to the workspace directory for the job and delete the .svn metadata folder (if it exists and is causing issues) or the entire workspace. Jenkins will then perform a fresh checkout.
    # On the Jenkins agent, in the job's workspace
rm -rf .svn # or rm -rf *
  • Why it works: This forces the SVN client to re-download all necessary metadata and code, bypassing any potentially corrupted local cache.

5. Network Issues or Server Unavailability

  • Diagnosis: Check the network connectivity from the Jenkins agent to the SVN server. Ping the server, and check if any firewalls or proxies are blocking access on the SVN port (e.g., 3690 for svn, 80/443 for http/https).
  • Fix: Resolve network issues, adjust firewall rules, or configure Jenkins agents to use the correct proxy settings if required.
  • Why it works: If the agent cannot reach the SVN server, it cannot perform the checkout.

After resolving these, your next potential roadblock might be an error related to build tools (like Maven or Gradle) not being configured correctly on the Jenkins agent.

Want structured learning?

Take the full Jenkins course →