github actions az command not found error runner missing cli bug

Not specified by the original author.

TL;DR

az is not recognized as an internal or external command means Windows cannot find the Azure CLI executable: the CLI installed but its folder is not on PATH, or the install did not finish. Reinstall from the official MSI with the add to PATH option checked, or add the install folder to PATH manually, then open a fresh terminal and verify with az version. A terminal opened before the fix will never see the new PATH.

'az' is not recognized as an internal or external command,
operable program or batch file.

Use this when

• cmd prints az is not recognized as an internal or external command, operable program or batch file
• PowerShell prints the term az is not recognized as the name of a cmdlet
• This happens right after installing the Azure CLI on Windows, or in a terminal that was open during the install

Not for this skill when

• az runs but az login fails. The CLI is found there; authentication is the problem, see the related application id skill below
• You are inside Azure Cloud Shell. Cloud Shell always has the CLI; a not recognized message there is a different issue

Steps

1. Check whether the CLI is actually installed. Look for Azure CLI in Add or remove programs, and for its folder under Program Files.

Expected: you know whether this is a missing install (go to step 3) or a PATH problem (go to step 2).

2. If it is installed, add its folder to PATH. Add the Azure CLI bin folder to the system PATH in Environment Variables, then close the terminal completely and open a new one.

Expected: az version prints version info in the fresh terminal.

3. If it is not installed, or the folder is missing, reinstall from the official MSI and keep the add to PATH option checked.

Expected: the installer completes, and a fresh terminal finds az.

4. In PowerShell, confirm the shell resolves it: Get-Command az.

Expected: it resolves to the CLI executable path instead of an error.

5. Verify the install end to end: az version.

Expected: JSON output with the Azure CLI version. Only now try az login or your original command.

Variant phrasings

az not recognized windows

The short version of the same report. It is the PATH problem in step 2 nine times out of ten; do the fresh-terminal check before reinstalling.

the term az is not recognized as the name of a cmdlet

The PowerShell wording of the identical failure. PowerShell and cmd read the same PATH, so the fix is the same: folder on PATH, fresh terminal, Get-Command az to confirm.

az login not recognized

az login never gets to run because the shell cannot find az at all. Fix PATH first (steps 1 to 5); login errors only become visible after az version works.

Root cause

The MSI installer optionally adds the CLI folder to PATH. Unchecking that option, an install that did not finish, or a terminal opened before the install leaves az unresolvable. The step everyone skips is opening a fresh terminal: already-open shells keep the old PATH forever.

Edge cases

• 32-bit and 64-bit installs land in different Program Files folders. Point PATH at the one that actually exists on disk.
• Corporate images sometimes block the MSI PATH change. Set PATH manually in System environment variables instead.
• Multiple Python-based CLI installs can shadow each other. Get-Command az shows which executable the shell actually resolved.

Tool compatibility

Azure CLI on Windows (MSI install), in cmd and PowerShell. The PATH principle is the same for winget installs; the folder location differs.

Related skills

• Please run az login to setup account - the next failure after az is found but not signed in: https://vectle.com/skills/skl_7aKi9fDg6cP5dqjxQPgTHA
• application id not found (AADSTS700016), which az login can hit once the CLI runs: https://vectle.com/skills/skl_A8TLFys-hrvLfD1hrxFnDg
• azure identity not found: https://vectle.com/skills/skl_O0wm7fdvw17HY02tjklDMw

Provenance

Built from the hatchjs.com Q and A on this exact error, linked in the evidence.

The hatchjs.com Q&A ("az is not recognized as an internal or external command") and the kthw-powershell execution troubleshooting notes document this exact failure: after installing the Azure CLI on Windows, the shell cannot find az because the install folder is not on PATH. The confirmed fix is reinstalling with PATH registration or adding the install folder to PATH manually, then opening a fresh terminal session so the new PATH takes effect.

Not specified by the original author.

TL;DR

The step fails because the working directory it was told to use does not exist in the runner's filesystem, usually because the repo was not checked out there or a default path assumed a different layout. Print the actual workspace tree in a debug step, then set the path explicitly.

No such file or directory: [PATH]

Steps

1. Add a debug step that prints the real filesystem layout:

- name: Debug workspace layout
  run: |
    pwd
    ls -la
    ls -la [SUSPECTED_PATH] || echo "path missing"

Expected: you see exactly which directories exist, and the suspected path is confirmed present or missing.

2. Check where the checkout actually landed:

gh run view [RUN_ID] --log | grep -i "checkout\|working directory" | head -10

Expected: the checkout step's destination path. If the repo went to a subdirectory or a custom path, every later working-directory must match it.

3. Set the working directory explicitly with a path you verified in step 1:

- name: [STEP NAME]
  working-directory: [VERIFIED_PATH]
  run: [COMMAND]

Expected: the step starts in a directory that exists, and the No such file or directory error is gone.

4. For repo-relative work, anchor on the workspace variable instead of guessing:

- run: |
    cd "${{ github.workspace }}/[SUBDIR]"
    [COMMAND]

Expected: the step resolves the path from the true workspace root on any runner OS.

5. Rerun the workflow and confirm the step executes:

gh run rerun [RUN_ID]

Expected: the previously failing step starts and runs your command instead of failing on the directory.

When to use

• A step fails with No such file or directory naming the working-directory
• The same workflow passes on one runner OS and fails on another
• Failures started after adding a custom checkout path or a container image

When not to use

• Your own command references a missing file; that is a path bug in the script, not the step's working directory
• The error names a missing binary; that is a PATH or installation problem
• Artifact download steps fail; that is an artifact name mismatch

Why it happens

GitHub evaluates working-directory before running your command, and it resolves relative paths against the default working directory, which differs between runner OSes and changes when actions/checkout uses a custom path. A path that exists on ubuntu-latest may not exist on windows-latest or inside a container, and the step fails before your first command line executes.

Edge cases

• defaults.run.working-directory applies to shell steps but not to all action steps; set it per step where it matters
• Composite actions run in their own context; a working-directory set in the caller does not always propagate inside
• Container jobs mount the workspace at a different path than the host default; verify with the debug step inside the container
• Matrix jobs that build different subdirectories need the directory parameterized per matrix entry, not hardcoded

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_V6V0x7UDDw88xuN2mOQuEQ

Resolved from the public thread: https://vectle.com/posts/pst_V6V0x7UDDw88xuN2mOQuEQ

Thread query: GitHub Actions "No such file or directory" for working-directory: path debugging

TL;DR: The step fails because the working directory it was told to use does not exist in the runner's filesystem, usually because the repo was not checked out there or a default path assumed a different layout. Print the actual workspace tree in a debug step, then set the path explicitly.

Not specified by the original author.

TL;DR: Install the Docker client in the job before using it, or move the job to a runner image that ships docker on PATH. The step assumes docker exists, but minimal runner images (and many self-hosted setups) do not put a docker client on PATH.

Error: Unable to locate executable file: docker.

The fix

1. Confirm which runner the job landed on and whether docker is present: add a debug step with which docker || echo MISSING.

   which docker || echo MISSING

   Expected: You see MISSING on the failing runner.

2. Either install the client in the job (apt-get install -y docker-ce-cli on Debian runners) or change runs-on to an image that includes it (e.g. ubuntu-latest for GitHub-hosted). Expected: docker --version prints a version.

3. Re-run the job. Expected: The docker step proceeds past executable lookup.

When this applies

• a run step fails immediately with Unable to locate executable file: docker
• self-hosted or custom container runners

When it does NOT apply

• docker exists but the daemon refuses (that is Cannot connect to the Docker daemon, a different error)
• the error names a different binary (same pattern, but check that tool's install docs)

Compatibility

GitHub Actions on self-hosted runners and container jobs; GitHub-hosted ubuntu/macos/windows images already ship docker.

Variants of this error

##[error]Unable to locate executable file: pnpm

Same pattern when the package manager is not on PATH; install it or fix the step order.

Error: Unable to locate executable file: unzip.

Same runner-image gap for unzip; install the package the same way.

Why it happens

The runner resolves every bare command through PATH at step start. Stock and minimal images deliberately omit tools the maintainer did not ask for, so the lookup fails before anything runs.

Edge cases and pitfalls

• Installing the client is not enough if there is no daemon; that surfaces as a daemon connection error next.
• In container jobs, the tool must exist inside the container, not on the runner host.
• PATH changes via $GITHUB_PATH only affect later steps, not the current one.

Seen in eyupio/zoomies PR 313: the Images job failed at its first Docker step with Error: Unable to locate executable file: docker because the runner pool's image carried no Docker client. The verified fix is to run Docker jobs on an image that includes the client. Source: https://github.com/eyupio/zoomies/pull/313