Skip to content

The Process '/usr/bin/git' Failed With Exit Code 128

Last updated

The process '/usr/bin/git' failed with exit code 128 means git hit a fatal error and stopped. Exit 128 is git's code for "fatal"; the reason is in the fatal: line just above. It most often comes from actions/checkout or from a git command in a run step, and the usual causes are authentication, a ref that does not exist, a shallow clone that lacks history, or file ownership in a container.

The exact message

Error: The process '/usr/bin/git' failed with exit code 128

Read the line before it. The common ones are listed below, each with its fix.

fatal: could not read Username or Authentication failed

The job needs credentials for a private repository. See could not read Username and Permission denied (publickey).

fatal: repository '...' not found

The repository: input is wrong, the repository was renamed or deleted, or the token cannot see it. GitHub reports a private repository you cannot access as "not found". Check the spelling and the token's access.

fatal: couldn't find remote ref or pathspec ... did not match

The branch, tag or SHA you asked for does not exist in that repository. This happens when a branch was deleted after a pull request merged, with ref: pointing at a stale name, or when a tag was never pushed.

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

For pull requests from forks the head branch lives in the fork, so use repository: ${{ github.event.pull_request.head.repo.full_name }} along with the ref, and be aware of the security implications of running fork code with secrets.

fatal: ... unknown revision after a shallow clone

By default actions/checkout fetches a single commit. Commands such as git log main..HEAD, git describe, git diff origin/main or a changelog generator then fail because the history is missing. Fetch more:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # full history and tags

fetch-depth: 0 fetches all history, which is slower on large repositories. If you only need a bit more, set a number like fetch-depth: 50, or run git fetch --depth=200 origin main before the command.

fatal: detected dubious ownership in repository

In a job that runs in a container:, the workspace is owned by a different user from the one running git, and git refuses to work in it. Mark it safe:

- run: git config --global --add safe.directory "$GITHUB_WORKSPACE"

Recent versions of actions/checkout do this for you in most cases, so also check that you are using a current major version.

fatal: not a git repository

The step ran before a checkout, or in the wrong directory. Add actions/checkout first, and check working-directory.

fatal: unable to access ... The requested URL returned error: 403

This is usually a push or fetch without the right token permission. See [Permission denied to github-actions[bot]](/errors/permission-to-repo-denied-to-github-actions-bot).

Submodules

A failing submodule fetch ends in exit code 128 as well. The submodule URL may be private (needs a token), may point to a commit that no longer exists upstream, or may use SSH. Run git submodule status locally and check that each pinned commit exists on its remote.

How to prevent it

  1. Pin actions/checkout to a current major version and read the fatal: line, not just the exit code.
  2. Set fetch-depth deliberately for steps that read history.
  3. Use a scoped token for any repository other than the current one.
  4. Delete workflow references to branches that get removed, and use SHAs for pull request builds.
  5. Keep submodule pointers on commits that are pushed.

FAQ

What does exit code 128 mean in git?

A fatal error. Git prints a fatal: message explaining it, and exits with 128.

Why does it say /usr/bin/git?

actions/checkout and other actions run git as a child process, and the runner reports which process failed and with what code.

Is it a GitHub outage?

If many unrelated workflows fail while fetching at once, check the GitHub status page. Otherwise the fatal: line points at your configuration.

Should I just re-run?

Only if the message looks like a network or server error (such as RPC failed or early EOF). Authentication and missing-ref errors will fail again.