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

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 368 views

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.

Quick fix

Fixes fatal: Could not read from remote repository during ls-remote

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

Verify Git is installed and accessible
Test repository connectivity manually
Fix GitHub Actions credential persistence
Update credentials in credential manager

git — error

$git --version
which git  # On Linux/Mac
where git  # On Windows
fatal: Could not read from remote repository during ls-remote

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.

Typical symptoms

Command "git ls-remote -h" returns exit code 128
Jenkins shows "Failed to connect to repository" error
GitHub Actions workflow fails at checkout step with credential errors
Error message includes "Invalid username or password"
CI pipeline cannot validate repository access
Works locally but fails in Docker containers or CI environments
Bower package installation fails with git ls-remote errors

Common causes

Invalid or expired authentication credentials (tokens, passwords)
GitHub Actions checkout persisting credentials that conflict with secondary repos
Git not installed or not in PATH (common in Jenkins/CI environments)
Incorrect personal access token syntax in repository URLs
Network proxy configuration interfering with Git connections
Cached credentials in credential manager pointing to wrong or expired tokens
SSH key not configured or not matching the remote repository
Repository URL typo or incorrect format
Outdated Git version with TLS compatibility issues

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 git@github.com: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:TOKEN@github.com/username/repo.git
# NOT: https://token:x-oauth-basic@github.com/...

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 git@github.com

# 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

Advanced notes

CI/CD Environment Considerations:
In containerized CI environments, avoid including the .git/ directory in Docker images as cached credentials can cause authentication failures.

Jenkins-Specific Configuration:
When using Jenkins with Git plugins, the repository URL field must exactly match the format your credentials expect. If credentials are configured for HTTPS, don't use SSH URLs and vice versa.

GitHub Actions Workflow Security:
The persist-credentials: false setting is particularly important in workflows that interact with multiple repositories or need to authenticate with different credentials mid-workflow. The default GITHUB_TOKEN has limited scope and may not work for operations on secondary repos.

Firewall and Network Policies:
Corporate networks may block Git protocols on non-standard ports. Ensure outbound connections are allowed on:
- HTTPS (port 443) for HTTPS URLs
- SSH (port 22) for SSH URLs
- Consider using HTTPS URLs instead of SSH in restricted environments

Credential Storage Security:
When using credential helpers in CI, prefer short-lived tokens or environment variables over stored credentials. Rotate tokens regularly and use minimal permission scopes.

Frequently asked questions

What does "fatal: Could not read from remote repository during ls-remote" mean?: 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.
How do I fix "fatal: Could not read from remote repository during ls-remote"?: 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 causes "fatal: Could not read from remote repository during ls-remote"?: Invalid or expired authentication credentials (tokens, passwords) GitHub Actions checkout persisting credentials that conflict with secondary repos Git not installed or not in PATH (common in Jenkins/CI environments)
Is the "fatal: Could not read from remote repository during ls-remote" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Git Official Documentation
📖
Git - git-ls-remote Documentation(Official Docs)
💬
jenkins - Failed to connect to repository : Command "git ls-remote -h" - Stack Overflow(Stack Overflow)
🐙
Github Actions - git command `ls-remote` fails for private repo when on runner - GitHub Discussion(GitHub)
💬
github - git ls-remote failed when using personal access token - Stack Overflow(Stack Overflow)
💬
git: fatal: Could not read from remote repository - Stack Overflow(Stack Overflow)

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

Quick fix

What this error means

Typical symptoms

Common causes

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

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading