GitHub Actions checkout "couldn't find remote ref"

By Kaveh Alemi·Latchkey

actions/checkout fetches the single ref you give it. A ref that was deleted, renamed, or never pushed, or a SHA outside the fetched depth, makes the fetch fail.

What this error means

A checkout step with a custom ref fails saying it could not find the remote ref, often after a force-push, a deleted branch, or a stale SHA.

Error: fatal: couldn't find remote ref refs/heads/feature/old-branch
The process '/usr/bin/git' failed with exit code 128

Common causes

Ref no longer exists on the remote

A branch or tag that was deleted or renamed after the run was queued cannot be fetched.

SHA outside the fetch depth

Checking out a specific commit that is deeper than fetch-depth (default 1) is not fetched.

How to fix it

Reference a ref that exists, with enough depth

1. Confirm the branch/tag still exists on the remote.
2. For an arbitrary SHA, set fetch-depth: 0 so full history is available.
3. Quote refs that contain slashes correctly in expressions.

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

How to prevent it

• Avoid hardcoding branch names that may be deleted.
• Use fetch-depth: 0 when checking out arbitrary commits.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions