What causes "usage: asdf exec " in asdf-vm/asdf?

Provide the command: `asdf exec node script.js`.

usage: asdf exec <command>

Error message

usage: asdf exec <command>

What it means

asdf's exec command returns this error when the command to execute is an empty string. execCommand needs a concrete command to resolve through asdf's version machinery and run; with no command there is nothing to do, so it prints and returns the usage error.

Source

Thrown at internal/cli/cli.go:575

		return err
	}

	finalEnv := execute.MergeWithCurrentEnv(env)
	err = exec.Exec(fname, realArgs, finalEnv)
	if err != nil {
		fmt.Printf("err %#+v\n", err.Error())
	}
	return err
}

func setPath(paths []string) string {
	return strings.Join(paths, string(os.PathListSeparator)) + string(os.PathListSeparator) + os.Getenv("PATH")
}

func execCommand(logger *log.Logger, command string, args []string) error {
	if command == "" {
		logger.Printf("usage: asdf exec <command>")
		return fmt.Errorf("usage: asdf exec <command>")
	}

	conf, err := config.LoadConfig()
	if err != nil {
		logger.Printf("error loading config: %s", err)
		return err
	}

	executable, plugin, version, err := getExecutable(logger, conf, command)
	if err != nil {
		return err
	}

	if len(args) > 1 {
		args = args[1:]
	} else {
		args = []string{}
	}

View on GitHub (pinned to 074a1722ca)

Solutions

Provide the command: `asdf exec node script.js`.
Check shell scripts for empty/unset variables before invoking `asdf exec $CMD`.
Use `asdf exec` with at least one positional argument after any flags.

Example fix

// before
CMD=""
asdf exec $CMD
// after
CMD="node"
asdf exec $CMD --version

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$CMD" ]; then echo "usage: asdf exec <command>" >&2; exit 1; fi
asdf exec "$CMD"

Try / catch

if ! asdf exec "$CMD" "$@" 2>err.log; then cat err.log >&2; exit $?; fi

Prevention

Pass the command as the first positional argument to asdf exec
Validate variables holding commands are non-empty in scripts
Prefer `asdf exec <cmd> -- args` form to avoid argument confusion

When it happens

Trigger: Running `asdf exec` with no arguments, or calling execCommand programmatically with command == "".

Common situations: Scripting asdf where a variable holding the command is empty (e.g. unset in a shell script); mistyping the invocation so the command argument is dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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