couldn't find remote ref (checkout) CI/CD Origin: Build & delivery Last updated 25 Oct 2026

GitHub Actions: fatal: couldn't find remote ref refs/heads/feature — The process '/usr/bin/git' failed with exit code 1 (actions/checkout)

actions/checkout could not fetch the branch, tag or SHA it was asked for — it was deleted, never pushed, or is not reachable with the default shallow fetch.

Exact message you may see fatal: couldn't find remote refcouldn't find remote ref refs/headsThe process '/usr/bin/git' failed with exit code 1checkout couldn't find remote ref
Explore the map of this error Full error map →
Seen on: GitHub Actions Git

Meaning

Checkout fetches a single commit (fetch-depth: 1) of the triggering ref. Asking for another ref, a tag, or history (for git describe, changelogs, diffs) fails unless you widen the fetch. Deleted branches and PRs from forks also yield this error.

Common causes

  • Branch deleted or renamed before the job ran
  • ref: input misspelled
  • Tags or full history needed but fetch-depth is 1
  • Fork PR ref not available with the given repository input
  • Private repository requires a token with access

⚡ Quick fix

  1. Check that ref: exists on the remote
  2. Use fetch-depth: 0 (and fetch-tags: true) when you need history or tags
  3. Pass repository: and token: for other repositories

Detailed fix by platform

GitHub Actions

  1. Verify the ref: git ls-remote origin refs/heads/feature

Code examples

Full history

yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    fetch-tags: true

How to diagnose

  1. Ref — Does it exist remotely?
  2. Depth — History needed?
  3. Repo — Same repository or another?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Build & delivery. Errors that are often confused with or caused by this one (click to open):

API rate limit exceeded — GitHub Actions: HttpError: API rate limit exceeded for installation ID 123456 / secondary rate limit (CI/CD)API rate limit exceed…Cache not found / Unable to reserve cache — GitHub Actions: Cache not found for input keys: npm-Linux-abc123 / Failed to save: Unable to reserve cache with key, another job may be creating this cache (CI/CD)Cache not found / Una…Credentials could not be loaded — GitHub Actions: Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers (CI/CD)Credentials could not…deprecated version of actions/upload-artifact — GitHub Actions: Error: This request has been automatically failed because it uses a deprecated version of `actions/upload-artifact: v3` (CI/CD)deprecated version of…Input required and not supplied — GitHub Actions: Error: Input required and not supplied: token (CI/CD)Input required and no…Process completed with exit code 1 — GitHub Actions: Error: Process completed with exit code 1. (CI/CD)Process completed wit…Resource not accessible by integration — GitHub Actions: Error: Resource not accessible by integration (403) (CI/CD)Resource not accessib…The process '/usr/bin/git' failed with exit code 128 — GitHub Actions: Error: The process '/usr/bin/git' failed with exit code 128 (CI/CD)The process '/usr/bin…couldn't …

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.