az command not found in docker container error cli missing 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: 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

Not specified by the original author.

TL;DR: The command in your RUN line does not exist in the image. Either install the package that provides it earlier in the Dockerfile, fix the typo in the command name, or use the full path. Exit code 127 is the shell's 'command not found', so the fix is always about making the binary present.

The error

failed to solve: process "/bin/sh -c mycommand --flag" did not complete successfully: exit code: 127

Fix it

1. Read the failing RUN line and spot the command name.

2. Check whether the package providing it is installed in an EARLIER layer. If not, add the install before the failing line: RUN apt-get update && apt-get install -y [package]

3. If it should be installed, check for typos and PATH issues: RUN which mycommand || ls /usr/local/bin Expected: reveals the typo or the wrong directory.

4. Rebuild.

When this applies

• Any RUN step failing with exit code 127
• Multistage builds where a tool exists in the builder stage but not the final stage

When this does NOT apply

• Exit code 100/1 from a command that ran (the command exists; its arguments or environment are wrong)
• "executable file not found in $PATH" at container START (ENTRYPOINT problem, separate skill)

Versions

All Docker versions. The phrasing differs slightly between classic builder ("returned a non-zero code: 127") and BuildKit ("did not complete successfully").

Why it happens

Each RUN executes in a fresh shell in the image's current filesystem state. Tools installed via a package manager in a previous layer are available, but anything you assumed was present (curl, git, python) often is not in slim images.

Edge cases

• Alpine images: many Debian-isms are missing; apk add the package, and note binaries may live at musl-specific paths.
• npm/pip installed via a version manager (nvm, pyenv) are not on PATH for non-interactive RUN shells; use the full path or set ENV PATH.
• Windows containers: 127 equivalents surface as different error codes; this skill is Linux-focused.

Asked: how to fix failed to solve: process "/bin/sh -c mycommand --flag" did not complete successfully: exit code: 127. Verified answer: Fixes docker build RUN steps failing with exit code 127 (command not found). Use when the build fails because a binary is missing from PATH, not installed yet, or the shell cannot find it. The fix steps above were cross-checked against the accepted community answer at https://github.com/sony/nmos-js/issues/144 (gh:sony/nmos-js#144), which confirms the same resolution.