asdf-vm/asdf · error

command not found

Error message

command not found

What it means

`asdf which <command>` looks up the command via shims.FindExecutable. When that returns shims.UnknownCommandError, meaning no shim exists for the command in the current directory's tool versions, the CLI translates it to 'command not found'.

Source

Thrown at internal/cli/cli.go:1451

		logger.Printf("error loading config: %s", err)
		return err
	}

	currentDir, err := os.Getwd()
	if err != nil {
		logger.Printf("unable to get current directory: %s", err)
		return err
	}

	if command == "" {
		fmt.Println("usage: asdf which <command>")
		return errors.New("must provide command")
	}

	path, _, _, _, err := shims.FindExecutable(conf, command, currentDir)
	if _, ok := err.(shims.UnknownCommandError); ok {
		logger.Printf("unknown command: %s. Perhaps you have to reshim?", command)
		return errors.New("command not found")
	}

	if _, ok := err.(shims.NoExecutableForPluginError); ok {
		logger.Printf("%s", err.Error())
		return errors.New("no executable for tool version")
	}

	if err != nil {
		fmt.Printf("unexpected error: %s\n", err.Error())
		return err
	}

	fmt.Printf("%s\n", path)
	return nil
}

func uninstallCommand(logger *log.Logger, tool, version string) error {
	if tool == "" || version == "" {

View on GitHub (pinned to 074a1722ca)

Solutions

1. Run `asdf reshim <tool> <version>` to regenerate shims for installed versions
2. Verify the tool is installed: `asdf list <tool>`; install it if not (`asdf install <tool> <version>`)
3. Check `.tool-versions` in the current directory and parents for the expected tool name/typos

Example fix

// before
$ asdf which terraform   # shim missing after install
// after
$ asdf reshim terraform 1.9.0 && asdf which terraform

if ! asdf list "$TOOL" >/dev/null 2>&1; then
  echo "tool not installed: $TOOL" >&2
  exit 1
fi

if path=$(asdf which "$CMD" 2>&1); then
  echo "$path"
else
  echo "$path"       # prints 'unknown command...' hint
  asdf reshim         # common remedy before retry
fi

When it happens

Trigger: Running `asdf which <cmd>` where the command is not provided by any installed plugin/version for the current directory, or shims are missing because `asdf reshim` was never run after installing a version.

Common situations: After installing a new tool version but not running `asdf reshim`; typos in the command name; tool not installed at all; working directory with no version pin and no global default.

Related errors

• executable not found
• command removed
• bad shell name
• no plugin name specified
• must provide command

AI-assisted analysis of asdf-vm/asdf@074a1722ca (2026-08-30). Data as JSON: /api/errors/3141032a45c1df4b. Report an issue: GitHub.