# How do I fix "Unable to locate executable file" in GitHub Actions?

"Unable to locate executable file" means a program is not on PATH. Five causes in order, from setup-node's cache to a missing file mode, each with the fix.

By Grant Unwin, published 2026-11-16. Checked against GitHub's documentation on 2026-11-16. The web page: https://www.runners.io/blog/github-actions-unable-to-locate-executable-file

“Unable to locate executable file: `name`” means an action looked for a program called `name` on the job’s PATH and did not find one it could run. The message comes from `@actions/io`, the library in GitHub’s actions toolkit for finding tools. Install the program before the step that needs it, or fix how it reaches PATH; this page lists 5 causes in the order to check them.

**In short**

- The message comes from @actions/io when a program an action needs is not on the job's PATH.
- The name after the colon is the missing program; read it first.
- setup-node with cache: pnpm runs pnpm store path, so install pnpm before it.
- A container or a minimal image can lack git, curl or ssh; install it in the first step.
- A PATH change reaches later steps only through $GITHUB\_PATH, and a script needs its executable bit.

This post covers where the message comes from, what the name in it tells you, the five causes with a change for each and how to find which tool a job is missing before the step that fails. The message text is from the library’s source and the behaviour of the actions from their own documentation, read on 15 November 2026.

## Where does “Unable to locate executable file” come from?

The library has a function called `which` that works like the command of that name: given a program, it looks through the directories in PATH and, on Windows, tries the extensions an executable can have. When it finds nothing, and the caller asked it to check, it throws an error. On Linux and macOS the full text is “Unable to locate executable file: tool. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable. Also check the file mode to verify the file is executable.” On Windows the last sentence changes to “Also verify the file has a valid extension for an executable file.”

So the message is not about the action that printed it. It is about the program the action tried to run: the name after the colon is the thing missing. Reports of the message on GitHub name `git`, `ssh`, `curl`, `mono` and `pnpm`, each from a different action, and the first thing to do with it is read that name.

A program can be installed and still not be found. The library searches the PATH of the process it runs in, and GitHub starts the bash of a `run` step with `--noprofile --norc`, so a directory that only a profile script adds, such as a version manager’s setup line in `.bashrc`, is not on a step’s PATH. A tool that works when you open a shell on your own machine can be missing in a job for that reason alone.

## Which cause is it?

| Cause | What you will see | The change |
| --- | --- | --- |
| setup-node caches pnpm or Yarn before it is installed | Unable to locate executable file: pnpm | Install the package manager in an earlier step |
| The job's container or image does not have the tool | Unable to locate executable file: git, ssh or curl | Install it first, or use an image that has it |
| A step put the tool on PATH in a way the next step cannot see | The tool works in the step that installed it, and not after | Write the directory to $GITHUB\_PATH |
| The file exists and is not executable | The message ends "check the file mode" | chmod +x it, and commit the mode |
| The name is wrong, or on Windows the extension is not in PATHEXT | The message ends "valid extension for an executable file" | Give the tool an extension PATHEXT lists, or call it through its shell |

## Why does setup-node fail with “Unable to locate executable file: pnpm”?

This one has a documented cause. When a workflow sets `cache: pnpm` on `actions/setup-node`, the action finds the directory to cache by running `pnpm store path --silent`, which needs pnpm to be installed already. If nothing earlier in the job has installed it, the call finds no program and the action throws this error. The setting for Yarn works the same way, with `yarn --version`.

The order of the steps in the action’s own example is the fix: install the package manager, then run `setup-node` with the cache setting, then install the dependencies. The example uses `pnpm/action-setup` for the first step, which is a third-party action, and the README says caching for Yarn and pnpm is off by default and has to be configured with the `cache` input.

```yaml
steps:
  - uses: actions/checkout@v7
  - uses: pnpm/action-setup@v6
    with:
      version: 10
  - uses: actions/setup-node@v7
    with:
      node-version: '24'
      cache: 'pnpm'
  - run: pnpm install --frozen-lockfile
  - run: pnpm test
```

## What if the tool is missing from the image or the container?

Then the job is running on something that has less than the workflow assumes. Two ways it happens are a job that runs in a container, and a job that moved to a runner with a smaller image. A container image is whatever its author put in it, and a minimal one often lacks `git`, `curl` or `ssh`, the three the reports name. GitHub says of its single-CPU runner, `ubuntu-slim`, that it has a minimal set of tools installed, so a workflow that moves to it from `ubuntu-latest` should be checked for tools it assumed. (Our 1 vCPU labels are the equivalent of it in size only: each is a machine of its own with our full image, listed below.)

Checkout is the instructive case. Its README says that when Git 2.18 or later is not in PATH the action falls back to downloading the files through the REST API, so a missing `git` alone does not stop it; a step that then runs `git` itself, or one that sets an `ssh-key` and needs the `ssh` client, does. A [report on the checkout repository](https://github.com/actions/checkout/issues/1942) shows exactly that for `ssh`, and a commenter there says it happens “only on self-hosted runners due to missing ssh-agent” and that `ubuntu-latest` works. The change is the same for each: install the program in the first step, or run the job on an image that has it.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    container: node:24-slim
    steps:
      - name: Install what the container lacks
        run: apt-get update && apt-get install -y git openssh-client curl
      - uses: actions/checkout@v7
```

On our runners the Ubuntu images carry `git`, `curl`, `jq`, Docker, the common language runtimes and the cloud CLIs, listed on the [runner image page](https://www.runners.io/docs/runners/image), which also names what is not there; anything else is one `apt-get install` away. Running the job in a container replaces that image with the container’s, so the list on the page is no longer the one that applies.

## Why does a tool I installed vanish in the next step?

Because each `run` step starts its own shell, and a variable exported in one shell is not in the next. A step that downloads a binary to `$HOME/.local/bin` and runs `export PATH=...` can call it in the same step, and the step after cannot. GitHub’s mechanism for this is the `GITHUB_PATH` file: a directory written to it is prepended to PATH for all later steps in the job, but not for the step that wrote it.

```yaml
- name: Install the tool
  run: |
    mkdir -p "$HOME/.local/bin"
    curl -fsSL -o "$HOME/.local/bin/mytool" "$TOOL_URL"
    chmod +x "$HOME/.local/bin/mytool"
    echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Use it
  run: mytool --version
```

## What if the file is there but is not executable?

The message says to check the file mode, and on Linux and macOS that is the permission bit. A script checked out from a repository keeps the mode Git recorded for it, so a script added from a system that does not set the executable bit arrives without it. `chmod +x` in the workflow is the quick fix. The fix that stays fixed is to record the mode in the repository, with `git update-index --chmod=+x path/to/script`, an option Git’s documentation describes as setting the execute permissions on the updated files, and to commit the change.

On Windows the library tries each extension listed in the `PATHEXT` variable, so a bare `build` finds `build.cmd` or `build.exe`. It does not find a file with no extension, or one whose extension is not in `PATHEXT`, such as `.ps1`, and the message’s last sentence says why. Call such a script through the shell that runs it, or give the tool an extension that `PATHEXT` lists.

## How do I find out which tool is missing before the step that fails?

Put a step ahead of the failing one that lists the tools the job needs and what PATH is, so a missing program is a line in the log and not an error in an action you did not write.

```yaml
- name: Which of these exist?
  run: |
    for t in git ssh curl pnpm node; do
      if command -v "$t" >/dev/null; then echo "ok      $t"; else echo "MISSING $t"; fi
    done
    echo "$PATH" | tr ':' '\n'
```

If a tool is missing on every run, install it. If it is present on one runner and missing on another, the two images differ, and the software list of each image is the place to compare. GitHub publishes the list for its own in the runner images repository, and the [labels page](https://www.runners.io/docs/runners/labels) and the image page above are ours. The [troubleshooting page](https://www.runners.io/docs/help/troubleshooting) covers jobs that do not start or that we stopped, and the [limits post](https://www.runners.io/blog/github-actions-limits) covers the failures that are a limit and not a missing program. For the cache that `setup-node` keeps, the [cache limit post](https://www.runners.io/blog/github-actions-cache-limit) has the rules.

## Sources

- [io.ts (actions/toolkit, @actions/io)](https://github.com/actions/toolkit/blob/main/packages/io/src/io.ts)
- [cache-utils.ts (actions/setup-node)](https://github.com/actions/setup-node/blob/main/src/cache-utils.ts)
- [actions/setup-node advanced usage](https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md)
- [actions/setup-node](https://github.com/actions/setup-node)
- [actions/checkout](https://github.com/actions/checkout)
- [Unable to locate executable file: ssh (actions/checkout issue 1942)](https://github.com/actions/checkout/issues/1942)
- [GitHub-hosted runners reference](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)
- [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands)
- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)
- [git-update-index (Git documentation)](https://git-scm.com/docs/git-update-index)

## Frequently asked questions

### What does "Unable to locate executable file" mean in GitHub Actions?

An action asked the @actions/io library to find a program on the job's PATH and found none it could run. The name after the colon is the missing program, and the message adds a check of the file mode, or on Windows of the extension.

### Why does setup-node fail with "Unable to locate executable file: pnpm"?

With cache: pnpm, setup-node runs pnpm store path to find the folder to cache, so pnpm must already be installed. Add pnpm/action-setup before setup-node, as the action's own example does.

### Why does a tool I installed disappear in the next step?

Each run step starts its own shell, so an exported PATH does not carry over. Append the directory to the file named by GITHUB\_PATH, and every later step in the job sees it; the step that wrote it does not.

### How do I make a script executable in GitHub Actions?

Run chmod +x on it in the workflow, or record the mode in the repository with git update-index --chmod=+x on the file and commit the change, so a checkout restores the executable bit.
