How to fix fatal: Could not read from remote repository during ls-remote in Git

GitINTERMEDIATEMEDIUM

Git ls-remote command fails when trying to query references from a remote repository, typically due to authentication issues, network problems, or incorrect repository URLs.

What this error means

The `git ls-remote` command is used to display references (branches, tags) available in a remote repository along with their commit IDs. This error occurs when Git cannot establish a connection to query the remote repository, which is often the first step in operations like cloning, fetching, or in CI/CD pipelines validating repository access. This failure typically manifests in automated environments like Jenkins, GitHub Actions, or CircleCI where credentials need to be properly configured. The command may fail with various exit codes (commonly 128) indicating that Git was unable to authenticate, reach the remote server, or parse the repository URL correctly. The error is particularly common when migrating between authentication methods (password to token), configuring new CI systems, or when network proxies interfere with Git operations.

How to fix "fatal: Could not read from remote repository during ls-remote"

1Verify Git is installed and accessible

First, confirm Git is installed and in your system PATH:

bash

git --version
which git  # On Linux/Mac
where git  # On Windows

In Jenkins, check: Manage Jenkins → Global Tool Configuration → Git and ensure the Git path is correct (e.g., C:\Program Files\Git\bin). If Git isn't installed, install it on your server:

bash

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install git

# CentOS/RHEL
sudo yum install git

# macOS
brew install git

2Test repository connectivity manually

Try running ls-remote manually to see the exact error:

bash

git ls-remote https://github.com/username/repo.git
# Or for SSH
git ls-remote [email protected]:username/repo.git

This will reveal whether it's an authentication, network, or URL issue.

3Fix GitHub Actions credential persistence

If working with multiple repositories in GitHub Actions, set persist-credentials: false:

yaml

- uses: actions/checkout@v4
  with:
    persist-credentials: false

This prevents the default GITHUB_TOKEN from interfering with authentication to secondary repositories.

4Update credentials in credential manager

Check and update cached credentials:

Windows:
1. Open Control Panel → Credential Manager → Windows Credentials
2. Find your Git credentials under Generic Credentials
3. Edit or remove outdated credentials

Linux/Mac:

bash

# Check current credential helper
git config --global credential.helper

# Clear cached credentials
git credential-cache exit
# Or for specific helper
git credential-osxkeychain erase

For GitHub: Remember that password authentication was removed August 2021. Use personal access tokens instead.

5Use correct personal access token syntax

If using tokens, the correct HTTPS URL format is:

bash

git ls-remote https://username:[email protected]/username/repo.git
# NOT: https://token:[email protected]/...

Or configure Git to use the token as password:

bash

git config --global credential.helper store
git ls-remote https://github.com/username/repo.git
# Enter username and paste token as password when prompted

6Check and fix proxy configuration

Remove or correct proxy settings that may block Git:

bash

# Check current proxy settings
git config --global --get http.proxy
git config --global --get https.proxy

# Remove proxy if not needed
git config --global --unset http.proxy
git config --global --unset https.proxy

# Or check ~/.gitconfig for proxy settings
cat ~/.gitconfig

Also check environment variables:

bash

unset http_proxy
unset https_proxy

7Verify SSH key configuration

For SSH URLs, ensure your SSH key is properly configured:

bash

# Test GitHub SSH connection
ssh -T [email protected]

# Check SSH agent has keys loaded
ssh-add -l

# Add your SSH key if needed
ssh-add ~/.ssh/id_rsa

Check .git/config to ensure the remote URL is correct:

bash

cat .git/config
# Verify [remote "origin"] url is correct

8Update Git to latest version

Older Git versions may have TLS compatibility issues:

bash

# Check current version
git --version

# Update Git (Ubuntu/Debian)
sudo apt-get update && sudo apt-get upgrade git

# Update Git (macOS)
brew upgrade git

# Update Git (Windows)
# Download latest from https://git-scm.com/downloads

How to fix fatal: Could not read from remote repository during ls-remote in Git

What this error means

Typical symptoms

Common causes

How to fix "fatal: Could not read from remote repository during ls-remote"

Advanced notes

Related errors

Official resources & further reading