How to fix fatal: couldn't find remote ref in Git

What this error means

The "fatal: Couldn't find remote ref refs/heads/branch-name" error indicates that Git attempted to fetch or checkout a branch from the remote repository, but that branch does not exist there. The refs/heads/ prefix refers to branches (as opposed to refs/tags/ for tags), and Git is explicitly stating it cannot find the specified branch reference. This error commonly appears in CI/CD environments where pipeline configurations reference branches that have been deleted, merged, or renamed since the configuration was written. It can also occur when a developer tries to checkout a branch that was only created locally by a teammate and never pushed to the remote. The error is particularly common after branch cleanup operations, pull request merges with automatic branch deletion enabled, or when switching between repositories that have different branch structures.

Typical symptoms

• Git fetch or git pull fails with 'Couldn't find remote ref' error
• CI/CD pipeline fails during checkout step with fatal error
• GitHub Actions, GitLab CI, or Jenkins job aborts at git checkout
• Attempting 'git checkout origin/branch-name' fails
• Error appears after a branch was recently merged or deleted
• Clone with specific branch flag fails: 'git clone -b branch-name'
• Submodule update fails when submodule references non-existent branch
• Deployment scripts fail when targeting specific branch

Common causes

1. The branch was deleted from the remote repository after merge
2. Branch name is misspelled or uses wrong casing
3. CI/CD pipeline configuration references an outdated branch name
4. Branch exists locally but was never pushed to the remote
5. Repository was forked and the branch only exists in the upstream repository
6. Default branch was renamed (e.g., master to main) but references not updated
7. Protected branch was force-deleted by admin
8. Submodule configuration points to a branch that no longer exists

How to fix "fatal: couldn't find remote ref"

# Fetch the latest remote info
git fetch origin

# List all remote branches
git branch -r

# Or list all branches (local and remote)
git branch -a

git reflog show --all | grep "branch-name"

# List remote branches and search for similar names
git branch -r | grep -i "branch"

# Check if using different casing
git branch -r | grep -i "feature"

# Prune deleted remote branches
git fetch --prune

# Or prune specifically from origin
git remote prune origin

# Verify the cleanup
git branch -r

# .github/workflows/ci.yml
on:
  push:
    branches:
      - main  # Update from old branch name
      - develop
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: main  # Ensure this branch exists

# .gitlab-ci.yml
default:
  # Remove hardcoded branch references if not needed

deploy:
  script:
    - echo "Deploying..."
  only:
    - main  # Update to existing branch

// Jenkinsfile
pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                git branch: 'main',  // Update branch name
                    url: 'https://github.com/user/repo.git'
            }
        }
    }
}

# Update your local default branch
git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

# Verify the change
git remote show origin

# Search for 'master' references in config files
grep -r "master" .github/ .gitlab-ci.yml Jenkinsfile 2>/dev/null

# If you have the branch locally
git push origin branch-name

# If you know the last commit hash
git checkout -b branch-name <commit-hash>
git push origin branch-name

# Check submodule status
git submodule status

# View submodule configuration
cat .gitmodules

[submodule "libs/mylib"]
    path = libs/mylib
    url = https://github.com/user/mylib.git
    branch = main  # Update to existing branch

git submodule sync
git submodule update --init --recursive

# Get the default branch name from remote
DEFAULT_BRANCH=$(git remote show origin | grep "HEAD branch" | cut -d ":" -f 2 | xargs)

# Use it in your commands
git checkout "$DEFAULT_BRANCH"
git pull origin "$DEFAULT_BRANCH"

- name: Get default branch
  run: |
    DEFAULT_BRANCH=$(git remote show origin | grep "HEAD branch" | cut -d ":" -f 2 | xargs)
    echo "DEFAULT_BRANCH=$DEFAULT_BRANCH" >> $GITHUB_ENV

- name: Checkout default
  run: git checkout ${{ env.DEFAULT_BRANCH }}

Advanced notes

# Shallow clone only fetches limited history
git clone --depth 1 https://github.com/user/repo.git

# If you need to checkout a different branch
git fetch --unshallow
git fetch origin other-branch
git checkout other-branch

git clone --depth 1 --branch main https://github.com/user/repo.git

# List remote refs without cloning
git ls-remote --heads origin

# Check for specific branch
git ls-remote --heads origin branch-name

# Returns nothing if branch doesn't exist
# Returns ref and hash if it does

- uses: actions/checkout@v4
  with:
    ref: ${{ github.event.pull_request.head.sha }}

GIT_TRACE=1 GIT_CURL_VERBOSE=1 git fetch origin branch-name

Frequently asked questions

What does "fatal: couldn't find remote ref" mean?

The "fatal: Couldn't find remote ref refs/heads/branch-name" error indicates that Git attempted to fetch or checkout a branch from the remote repository, but that branch does not exist there. The refs/heads/ prefix refers to branches (as opposed to refs/tags/ for tags), and Git is explicitly stating it cannot find the specified branch reference. This error commonly appears in CI/CD environments where pipeline configurations reference branches that have been deleted, merged, or renamed since the configuration was written.

How do I fix "fatal: couldn't find remote ref"?

Fix Git's "fatal: couldn't find remote ref" error caused by deleted, renamed, or stale branch refs. Run git fetch --prune and check the exact branch name.

What causes "fatal: couldn't find remote ref"?

The branch was deleted from the remote repository after merge Branch name is misspelled or uses wrong casing CI/CD pipeline configuration references an outdated branch name

Is the "fatal: couldn't find remote ref" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• fatal: git fetch-pack: expected shallow list. Shallow clone may not have all commits

  How to fix 'expected shallow list' and shallow clone missing commits in Git

  MEDIUM

• git-lfs not installed in CI environment

  How to fix 'git-lfs not installed in CI environment' error

  MEDIUM

• error: sparse-checkout is not supported in this CI environment

  How to fix 'sparse-checkout is not supported in this CI environment' in Git

  MEDIUM

• fatal: unknown option --no-optional-locks (git version too old)

  How to fix 'unknown option --no-optional-locks' (git version too old) in Git

  LOW

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 📖
  git-fetch Documentation - Git SCM(Official Docs)
• 📖
  git-ls-remote Documentation - Git SCM(Official Docs)
• 📖
  Git References (Refs) - Pro Git Book(Official Docs)
• 🐙
  Renaming a branch - GitHub Docs(GitHub)
• 💬
  Git pull error: couldn't find remote ref - Stack Overflow(Stack Overflow)