{"record":{"id":"1b3a7334f56eee1c","repo":"docker/cli","slug":"docker-w-run-docker-s-help-for-more-inform","errorCode":null,"errorMessage":"docker: %w\n\nRun 'docker %s --help' for more information","messagePattern":"docker: %w\n\nRun 'docker (.+?) --help' for more information","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/run.go","lineNumber":319,"sourceCode":"\t\t\t\toutputStream: out,\n\t\t\t\terrorStream:  cerr,\n\t\t\t\tresp:         resp.HijackedResponse,\n\t\t\t\ttty:          config.Tty,\n\t\t\t\tdetachKeys:   options.DetachKeys,\n\t\t\t}\n\n\t\t\tif errHijack := streamer.stream(ctx); errHijack != nil {\n\t\t\t\treturn errHijack\n\t\t\t}\n\t\t\treturn errAttach\n\t\t}()\n\t}()\n\treturn resp.HijackedResponse.Close, nil\n}\n\n// withHelp decorates the error with a suggestion to use \"--help\".\nfunc withHelp(err error, commandName string) error {\n\treturn fmt.Errorf(\"docker: %w\\n\\nRun 'docker %s --help' for more information\", err, commandName)\n}\n\n// toStatusError attempts to detect specific error-conditions to assign\n// an appropriate exit-code for situations where the problem originates\n// from the container. It returns [cli.StatusError] with the original\n// error message and the Status field set as follows:\n//\n// - 125: for generic failures sent back from the daemon\n// - 126: if container start fails with 'permission denied' error\n// - 127: if container start fails with 'not found'/'no such' error\nfunc toStatusError(err error) error {\n\t// TODO(thaJeztah): some of these errors originate from the container: should we actually suggest \"--help\" for those?\n\n\terrMsg := err.Error()\n\n\tif strings.Contains(errMsg, \"executable file not found\") || strings.Contains(errMsg, \"no such file or directory\") || strings.Contains(errMsg, \"system cannot find the file specified\") {\n\t\treturn cli.StatusError{\n\t\t\tCause:      err,","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/run.go#L301-L337","documentation":"This is the withHelp wrapper applied around errors in the docker run path (runRun, parse failures, validatePullOpt, and toStatusError). It formats the original error then appends a hint to run 'docker run --help'. It is a presentation wrapper, not a distinct error; the underlying cause is the wrapped error.","triggerScenarios":"Any error during docker run parsing/validation (bad flags, invalid pull policy, device/path parse errors) or toStatusError paths (executable not found → exit 127, permission denied → exit 126, generic daemon error → 125). The wrapper decorates the message.","commonSituations":"Misspelled flags; --pull with bad value; image/entrypoint not found inside the container; permission denied on the entrypoint; wrong command name after the image. The appended help hint helps users discover correct syntax.","solutions":["Read the part before 'docker:' to find the root cause, then fix flags/args","Run docker run --help to see valid flags","For exit 127 (executable not found): verify the entrypoint/cmd and image","For exit 126 (permission denied): check the binary permissions and user"],"exampleFix":"# before\ndocker run --pull=alwys img   # docker: invalid pull option ...\n# after\ndocker run --pull=always img","handlingStrategy":"try-catch","validationCode":"// Pre-validate flags and image/entrypoint before invoking `docker run`.\nif !validPullPolicy(pullOpt) {\n    return fmt.Errorf(\"bad --pull value: %s\", pullOpt)\n}","typeGuard":null,"tryCatchPattern":"// Differentiate exit codes from the wrapped message.\nvar se cli.StatusError\nif errors.As(err, &se) {\n    switch se.StatusCode {\n    case 127:\n        // entrypoint not found\n    case 126:\n        // permission denied\n    default:\n        // generic 125\n    }\n}","preventionTips":["Parse the StatusCode of cli.StatusError to branch on 125/126/127 rather than string-matching"],"tags":["docker","run","help-wrapper","exit-code"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}