What causes "invalid usage" in golang/go?

Read the rendered UsageError message; it prints `usage: [?]` ([&] if async).

ErrUsage

ErrUsage

Error message

invalid usage

What it means

ErrUsage is a sentinel commands return (and conditions return) to signal invalid arguments; the engine recognizes it and converts the failure into a *UsageError whose Error() renders the command's correct usage string. It is the canonical 'you called me wrong' signal and is recoverable: the script author fixes the arguments and reruns.

Source

Thrown at src/cmd/internal/script/errors.go:64

//
// It may be returned in response to invalid arguments.
type UsageError struct {
	Name    string
	Command Cmd
}

func (e *UsageError) Error() string {
	usage := e.Command.Usage()
	suffix := ""
	if usage.Async {
		suffix = " [&]"
	}
	return fmt.Sprintf("usage: %s %s%s", e.Name, usage.Args, suffix)
}

// ErrUsage may be returned by a Command to indicate that it was called with
// invalid arguments; its Usage method may be called to obtain details.
var ErrUsage = errors.New("invalid usage")

View on GitHub (pinned to b6b368adc5)

Solutions

Read the rendered UsageError message; it prints `usage: <name> <args> [?]` ([&] if async).
Run `help <command>` in the script to see full usage and detail.
Correct the arguments in the script line to match the synopsis.

Example fix

// before (script.txt)
cp onlyonearg
# -> usage: cp src... dst

// after
cp a.txt b.txt outdir/

Defensive patterns

Strategy: try-catch

Validate before calling

// Usage is a static contract; validate args before writing the script line per the synopsis.

Type guard

func isUsage(err error) bool {
    var ue *script.UsageError
    return errors.As(err, &ue)
}

Try / catch

if err := impl.Run(s, args...); err != nil {
    if errors.Is(err, script.ErrUsage) {
        // re-render usage for the user
    }
}

Prevention

Run `help <command>` to learn each command's signature.
Match argument counts and flags to the usage synopsis.
Use errors.As to *UsageError for structured handling.

When it happens

Trigger: A script command receives the wrong number/type of arguments, e.g. Cp with < 2 args, a flag command missing its value, or a condition missing its required argument. The command returns ErrUsage; the engine wraps it so the failure message includes the usage synopsis.

Common situations: Script-test author mis-remembers a command's signature, omits a required argument, or passes an unknown flag. The rendered UsageError usually tells them exactly what was expected.

Related errors

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