Home / Blog / Runners and limits
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.
“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.
- 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.
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 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.
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, 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.
- 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.
- 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 and the image page above are ours. The troubleshooting page covers jobs that do not start or that we stopped, and the limits post covers the failures that are a limit and not a missing program. For the cache that setup-node keeps, the cache limit post has the rules.
Sources
- io.ts (actions/toolkit, @actions/io) (github.com)
- cache-utils.ts (actions/setup-node) (github.com)
- actions/setup-node advanced usage (github.com)
- actions/setup-node (github.com)
- actions/checkout (github.com)
- Unable to locate executable file: ssh (actions/checkout issue 1942) (github.com)
- GitHub-hosted runners reference (docs.github.com)
- Workflow commands for GitHub Actions (docs.github.com)
- Workflow syntax for GitHub Actions (docs.github.com)
- git-update-index (Git documentation) (git-scm.com)
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.