TeamCity build step "command not found" on the agent in CI

A command-line step invoked a program the agent shell could not find. The tool is either not installed on the agent or not on the PATH the agent process uses, which differs from an interactive shell.

What this error means

A step fails with "<tool>: command not found" (exit code 127) even though the same command works when run manually on the agent host.

TeamCity

[Step 1/3] Command Line
/opt/agent/temp/buildTmp/script.sh: line 3: pnpm: command not found
Process exited with code 127

Common causes

The tool is not installed on the agent

The agent host lacks the program the step calls, so the shell cannot resolve it.

The tool is installed but not on the agent PATH

The agent service runs with a different environment than a login shell, so a tool in a user-specific path is not found.

How to fix it

Install the tool on the agent and expose it

Install the required tool on the agent host, or use a build step that provisions it.
Confirm its directory is on the PATH the agent process uses (set it in buildAgent.properties env or the service environment).
Restart the agent so the new PATH takes effect, then re-run.

buildAgent.properties

# expose a tool directory to the agent via buildAgent.properties
env.PATH=%env.PATH%;/opt/tools/bin

Call the tool by absolute path

If PATH cannot be changed, invoke the executable by its full path in the step so resolution does not depend on PATH.

How to prevent it

Bake required tools into the agent image so every agent has them.
Set tool paths in the agent environment, not just interactive shells.
Use agent requirements so only agents with the tool run the build.