docker/cli · error

docker: Run 'docker --help' for more information

Error message

docker: %w

Run 'docker %s --help' for more information

What it means

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.

Solutions

1. Read the part before 'docker:' to find the root cause, then fix flags/args
2. Run docker run --help to see valid flags
3. For exit 127 (executable not found): verify the entrypoint/cmd and image
4. For exit 126 (permission denied): check the binary permissions and user

Example fix

# before
docker run --pull=alwys img   # docker: invalid pull option ...
# after
docker run --pull=always img

// Pre-validate flags and image/entrypoint before invoking `docker run`.
if !validPullPolicy(pullOpt) {
    return fmt.Errorf("bad --pull value: %s", pullOpt)
}

// Differentiate exit codes from the wrapped message.
var se cli.StatusError
if errors.As(err, &se) {
    switch se.StatusCode {
    case 127:
        // entrypoint not found
    case 126:
        // permission denied
    default:
        // generic 125
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• conflicting options: cannot specify both --attach and…
• every ip-range or gateway must have a corresponding subnet
• multiple overlapping subnet configuration is not supported
• network prune has been cancelled
• node ID not found in /info

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/1b3a7334f56eee1c. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/container/run.go:319

				outputStream: out,
				errorStream:  cerr,
				resp:         resp.HijackedResponse,
				tty:          config.Tty,
				detachKeys:   options.DetachKeys,
			}

			if errHijack := streamer.stream(ctx); errHijack != nil {
				return errHijack
			}
			return errAttach
		}()
	}()
	return resp.HijackedResponse.Close, nil
}

// withHelp decorates the error with a suggestion to use "--help".
func withHelp(err error, commandName string) error {
	return fmt.Errorf("docker: %w\n\nRun 'docker %s --help' for more information", err, commandName)
}

// toStatusError attempts to detect specific error-conditions to assign
// an appropriate exit-code for situations where the problem originates
// from the container. It returns [cli.StatusError] with the original
// error message and the Status field set as follows:
//
// - 125: for generic failures sent back from the daemon
// - 126: if container start fails with 'permission denied' error
// - 127: if container start fails with 'not found'/'no such' error
func toStatusError(err error) error {
	// TODO(thaJeztah): some of these errors originate from the container: should we actually suggest "--help" for those?

	errMsg := err.Error()

	if strings.Contains(errMsg, "executable file not found") || strings.Contains(errMsg, "no such file or directory") || strings.Contains(errMsg, "system cannot find the file specified") {
		return cli.StatusError{
			Cause:      err,

View on GitHub (pinned to 4f84911bfe)