- integrations
- Dev Containers
- Troubleshooting
- Fix a tool missing from the terminal
Fix a tool missing from the terminal
The container started and the restore worked, but a project tool is missing from PATH in a terminal.
Find the message below.
Every entry shows the message as the shell prints it, the cause, and the fix.
A new interactive shell activates a project only when the project lies under a consentPaths entry.
The shell reads the project once, when it starts.
ocx exec -- <command> finds the project tools in every case.
For a warning printed during container creation, see Fix a lock or permission error or Fix a restore warning.
Error: the tool is not on PATH outside consentPaths
bash: shfmt: command not foundThis issue occurs when the project directory is not under a consentPaths entry.
The default entry is /workspaces/*, so a project in /tmp, in your home directory or in a mount elsewhere does not activate.
The shell runs no ocx command for it and leaves PATH unchanged.
The tools are still locked and present, and ocx exec runs them:
$ ocx exec -- shfmt --versionv3.13.1To fix it, use one of these:
- Run the tool through
ocx exec -- <command>, or open a shell in the project environment withocx shell. - Move the project below
/workspaces. - Add the project path to
consentPathsand rebuild the container.
A plain path matches that directory only, and dir/* matches the directory and everything below it.
Any other use of * matches nothing, and an empty consentPaths activates nothing.
This setting lets the project’s ocx.toml shape every new shell in that directory, so What the feature trusts says what to weigh first.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": { "consentPaths": "/workspaces/*:/tmp/proj" } }}After the rebuild, a new terminal started in /tmp/proj finds the tool.
$ bash -ic 'shfmt --version'v3.13.1Error: command not found in a terminal inside the project
bash: shfmt: command not foundThis issue occurs when the project is under consentPaths but the shell did not compose the tools.
Three causes are common.
The lock is missing or stale, as Error: ocx.lock not found and Error: ocx.lock is stale show.
The terminal started before ocx lock or ocx pull finished, or before the project existed.
Or shellActivation is false, so no shell gets the toolchain.
The feature composes PATH once, when an interactive shell starts in the project.
A terminal that is already open does not change after ocx add or ocx pull, and cd into the project does not activate it.
With pullGroups set, only those groups are on PATH, and a named list replaces the default group.
To fix it:
- Open a new terminal after the lock and the tools are in place.
- Run the tool through
ocx exec, which always works:ocx exec -- shfmt --version. - If the option is off, remove
"shellActivation": falsefromdevcontainer.jsonand rebuild.
$ ocx exec -- shfmt --versionv3.13.1With shellActivation set to false, command -v shfmt prints nothing and exits with status 1, while the ocx exec call still prints v3.13.1.
A script run with sh -lc is not an interactive shell either, so use ocx exec there.