{"record":{"id":"671fe1d5417ae95a","repo":"golang/go","slug":"errusage","errorCode":"ErrUsage","errorMessage":"invalid usage","messagePattern":"invalid usage","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/cmd/internal/script/errors.go","lineNumber":64,"sourceCode":"//\n// It may be returned in response to invalid arguments.\ntype UsageError struct {\n\tName    string\n\tCommand Cmd\n}\n\nfunc (e *UsageError) Error() string {\n\tusage := e.Command.Usage()\n\tsuffix := \"\"\n\tif usage.Async {\n\t\tsuffix = \" [&]\"\n\t}\n\treturn fmt.Sprintf(\"usage: %s %s%s\", e.Name, usage.Args, suffix)\n}\n\n// ErrUsage may be returned by a Command to indicate that it was called with\n// invalid arguments; its Usage method may be called to obtain details.\nvar ErrUsage = errors.New(\"invalid usage\")\n","sourceCodeStart":46,"sourceCodeEnd":65,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/internal/script/errors.go#L46-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (script.txt)\ncp onlyonearg\n# -> usage: cp src... dst\n\n// after\ncp a.txt b.txt outdir/","handlingStrategy":"try-catch","validationCode":"// Usage is a static contract; validate args before writing the script line per the synopsis.","typeGuard":"func isUsage(err error) bool {\n    var ue *script.UsageError\n    return errors.As(err, &ue)\n}","tryCatchPattern":"if err := impl.Run(s, args...); err != nil {\n    if errors.Is(err, script.ErrUsage) {\n        // re-render usage for the user\n    }\n}","preventionTips":["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."],"tags":["script","usage","test-framework","sentinel-error"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}