golang/go · error

unknown command

Error message

unknown command

What it means

Returned by Engine.runCommand when the parsed command name has no entry in the Engine's Cmds map (impl == nil). The engine dispatches command names to registered Cmd implementations; an unregistered name is treated as a script error wrapped via cmdError so it carries the command's source location.

Source

Thrown at src/cmd/internal/script/engine.go:550

				return false, fmt.Errorf("condition %q requires a suffix", cond.tag)
			}
		}
		active, err := impl.Eval(s, suffix)

		if err != nil {
			return false, fmt.Errorf("evaluating condition %q: %w", cond.tag, err)
		}
		if active != cond.want {
			return false, nil
		}
	}

	return true, nil
}

func (e *Engine) runCommand(s *State, cmd *command, impl Cmd) error {
	if impl == nil {
		return cmdError(cmd, errors.New("unknown command"))
	}

	async := impl.Usage().Async
	if cmd.background && !async {
		return cmdError(cmd, errors.New("command cannot be run in background"))
	}

	wait, runErr := impl.Run(s, cmd.args...)
	if wait == nil {
		if async && runErr == nil {
			return cmdError(cmd, errors.New("internal error: async command returned a nil WaitFunc"))
		}
		return checkStatus(cmd, runErr)
	}
	if runErr != nil {
		return cmdError(cmd, errors.New("internal error: command returned both an error and a WaitFunc"))
	}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Check the command spelling against the registered Cmds (use the Help command to list them).
2. Ensure your Engine was built with the full command set, e.g. include script.DefaultCmds().
3. Register the custom command you intended to call.

Example fix

// before
eng := &script.Engine{Cmds: map[string]script.Cmd{}} // empty
// script: 'cp a b' -> unknown command

// after
eng := &script.Engine{Cmds: script.DefaultCmds()}

// Confirm a command name is registered before running the script.
func knownCommand(name string, cmds map[string]script.Cmd) bool {
    _, ok := cmds[name]
    return ok
}

func isUnknownCommand(err error) bool {
    var ce *script.CommandError
    return errors.As(err, &ce) && ce.Err != nil && ce.Err.Error() == "unknown command"
}

// Surface registered command names in test output for easy debugging.

When it happens

Trigger: A script line invoking a command name that was not registered in Engine.Cmds — a typo, a removed/renamed command, or a custom engine that registered only a subset. Distinct from a command returning an error at runtime: this fires before Run is called.

Common situations: Typo in a script-test command (e.g. `mvv` instead of `mv`), using a command that only exists in a different engine configuration, or forgetting to include script.DefaultCmds() when building a custom Cmds map.

Related errors

• no engine configured
• command cannot be run in background
• destination is not a directory
• duplicated '!' or '?' token
• empty condition

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/6af01182d71d05c9. Report an issue: GitHub.