cli/command: rewrite user-facing error messages flagged by the audit

Applies the rewrites produced by an end-to-end review of CLI error
quality (audit/{inventory,review,rewrites,editorial}.json). 31 messages
across 11 command areas, organised around the patterns that surfaced
most often:

  Factual / wrong-noun fixes — messages that misdirected users to the
  wrong layer or named things that didn't exist:
    - image/list: --show-digest -> --digests (the actual flag name)
    - image/load: stdin-state assertion now matches IsTerminal() guard
    - inspect: template execution failures no longer mislabelled as
      parsing errors
    - system/info: blames the actual cause (info collection) not
      pretty-printing
    - image/save, container/export: -o open failures name the file,
      not the operation
    - image/build: build-context errors enumerate supported forms
      instead of misnaming everything as a missing path
    - manifest/annotate: prints the os/arch pair actually validated
    - context/options: describes the missing-endpoint state rather
      than implying a fetch failure
    - container/cp: corrects the misleading 'container source' wording

  Partial success surfaced — operations that succeeded with a
  follow-up failure now say so, preventing wasted retries:
    - container/create: cidfile write failure (container exists)
    - image/build: aux-message decode failure (build succeeded)
    - image/build: missing image ID for --iidfile (build succeeded)

  Refusal reason explained — TTY-refusal messages for binary tar
  output now state why instead of using 'cowardly':
    - container/export, context/export, image/save

  Echo-the-value / name-the-flag — validation errors now include
  what the user typed and the expected form:
    - container/opts: --pid, --uts, --userns, --cgroupns,
      --storage-opt, --device (×2 branches), --log-driver
    - network/connect: --driver-opt
    - network/create: --subnet (names both overlapping subnets)
    - volume/update, container/update, context/create

  Internal jargon replaced — code-level field names removed from
  user-facing wording:
    - container/exec: 'exec ID empty' replaced with daemon-anomaly
      framing

  Cause preserved — manifest/push: ErrBlobCreated is now wrapped via
  %w and the wording describes what actually happened.

Errors that have an actionable hint use internal/hint.Wrap so the
hint is rendered separately from the message at the top-level error
handler. Errors that benefit from a sibling-site fix (image/build's
context detection in image/build/context_detect.go) carry that fix
to keep the same condition producing the same wording regardless of
entry point.

Tests updated to match the new wordings; substring-based assertions
stay stable because hints are no longer part of err.Error().

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

Author: dvdksn

cli/command/container/cp.go

@@ -16,6 +16,7 @@ import (
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/streams"
+	"github.com/docker/cli/internal/hint"
 	"github.com/docker/go-units"
 	"github.com/moby/go-archive"
 	"github.com/moby/moby/client"
@@ -242,7 +243,10 @@ func runCopy(ctx context.Context, dockerCli command.Cli, opts copyOptions) error
 	case acrossContainers:
 		return errors.New("copying between containers is not supported")
 	default:
-		return errors.New("must specify at least one container source")
+		return hint.Wrap(
+			errors.New("one argument must reference a container as 'CONTAINER:PATH'"),
+			"Use 'docker cp CONTAINER:SRC LOCAL' to copy from a container, or 'docker cp LOCAL CONTAINER:DEST' to copy into one.",
+		)
 	}
 }
 

cli/command/container/cp_test.go

@@ -38,7 +38,7 @@ func TestRunCopyWithInvalidArguments(t *testing.T) {
 				source:      "./source",
 				destination: "./dest",
 			},
-			expectedErr: "must specify at least one container source",
+			expectedErr: "one argument must reference a container as 'CONTAINER:PATH'",
 		},
 	}
 	for _, testcase := range testcases {

cli/command/container/create.go

@@ -20,6 +20,7 @@ import (
 	"github.com/docker/cli/cli/config/configfile"
 	"github.com/docker/cli/cli/config/types"
 	"github.com/docker/cli/cli/streams"
+	"github.com/docker/cli/internal/hint"
 	"github.com/docker/cli/internal/jsonstream"
 	"github.com/docker/cli/opts"
 	"github.com/moby/moby/api/types/mount"
@@ -188,7 +189,10 @@ func (cid *cidFile) Write(id string) error {
 		return nil
 	}
 	if _, err := cid.file.WriteString(id); err != nil {
-		return fmt.Errorf("failed to write the container ID (%s) to file: %w", id, err)
+		return hint.Wrap(
+			fmt.Errorf("container %s was created, but writing its ID to %s failed: %w", id, cid.path, err),
+			fmt.Sprintf("The container exists on the daemon. Run 'docker rm %s' to remove it, or note the ID for later use.", id),
+		)
 	}
 	cid.written = true
 	return nil

cli/command/container/exec.go

@@ -10,6 +10,7 @@ import (
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/command/completion"
 	"github.com/docker/cli/cli/config/configfile"
+	"github.com/docker/cli/internal/hint"
 	"github.com/docker/cli/opts"
 	"github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/client"
@@ -115,7 +116,10 @@ func RunExec(ctx context.Context, dockerCLI command.Cli, containerIDorName strin
 
 	execID := response.ID
 	if execID == "" {
-		return errors.New("exec ID empty")
+		return hint.Wrap(
+			errors.New("the Docker daemon returned an empty response when creating the exec session"),
+			"This is unexpected — please report it at https://github.com/moby/moby/issues with the daemon version ('docker version') and the command you ran.",
+		)
 	}
 
 	if options.Detach {

cli/command/container/exec_test.go

@@ -195,7 +195,7 @@ func TestRunExec(t *testing.T) {
 		{
 			doc:           "missing exec ID",
 			options:       NewExecOptions(),
-			expectedError: "exec ID empty",
+			expectedError: "the Docker daemon returned an empty response when creating the exec session",
 			client:        &fakeClient{},
 		},
 	}

cli/command/container/export.go

@@ -9,6 +9,7 @@ import (
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/command/completion"
+	"github.com/docker/cli/internal/hint"
 	"github.com/moby/moby/client"
 	"github.com/moby/sys/atomicwriter"
 	"github.com/spf13/cobra"
@@ -49,13 +50,16 @@ func runExport(ctx context.Context, dockerCLI command.Cli, opts exportOptions) e
 	var output io.Writer
 	if opts.output == "" {
 		if dockerCLI.Out().IsTerminal() {
-			return errors.New("cowardly refusing to save to a terminal. Use the -o flag or redirect")
+			return hint.Wrap(
+				errors.New("refusing to write a binary tar archive to the terminal"),
+				"Use '-o FILE' to write to a file, or redirect stdout, e.g. 'docker container export CONTAINER > out.tar'.",
+			)
 		}
 		output = dockerCLI.Out()
 	} else {
 		writer, err := atomicwriter.New(opts.output, 0o600)
 		if err != nil {
-			return fmt.Errorf("failed to export container: %w", err)
+			return fmt.Errorf("cannot open output file %q: %w", opts.output, err)
 		}
 		defer writer.Close()
 		output = writer

cli/command/container/export_test.go

@@ -44,6 +44,6 @@ func TestContainerExportOutputToIrregularFile(t *testing.T) {
 	cmd.SetErr(io.Discard)
 	cmd.SetArgs([]string{"-o", "/dev/random", "container"})
 
-	const expected = `failed to export container: cannot write to a character device file`
+	const expected = `cannot open output file "/dev/random": cannot write to a character device file`
 	assert.Error(t, cmd.Execute(), expected)
 }

cli/command/container/opts.go

@@ -18,6 +18,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/docker/cli/internal/hint"
 	"github.com/docker/cli/internal/lazyregexp"
 	"github.com/docker/cli/internal/volumespec"
 	"github.com/docker/cli/opts"
@@ -517,22 +518,34 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 
 	pidMode := container.PidMode(copts.pidMode)
 	if !pidMode.Valid() {
-		return nil, errors.New("--pid: invalid PID mode")
+		return nil, hint.Wrap(
+			fmt.Errorf("invalid --pid mode %q", copts.pidMode),
+			"Valid forms are 'host' or 'container:<name|id>'.",
+		)
 	}
 
 	utsMode := container.UTSMode(copts.utsMode)
 	if !utsMode.Valid() {
-		return nil, errors.New("--uts: invalid UTS mode")
+		return nil, hint.Wrap(
+			fmt.Errorf("invalid --uts mode %q", copts.utsMode),
+			"The only valid form is 'host'.",
+		)
 	}
 
 	usernsMode := container.UsernsMode(copts.usernsMode)
 	if !usernsMode.Valid() {
-		return nil, errors.New("--userns: invalid USER mode")
+		return nil, hint.Wrap(
+			fmt.Errorf("invalid --userns mode %q", copts.usernsMode),
+			"The only valid form is 'host'.",
+		)
 	}
 
 	cgroupnsMode := container.CgroupnsMode(copts.cgroupnsMode)
 	if !cgroupnsMode.Valid() {
-		return nil, errors.New("--cgroupns: invalid CGROUP mode")
+		return nil, hint.Wrap(
+			fmt.Errorf("invalid --cgroupns mode %q", copts.cgroupnsMode),
+			"Valid forms are 'private' or 'host'.",
+		)
 	}
 
 	restartPolicy, err := opts.ParseRestartPolicy(copts.restartPolicy)
@@ -920,7 +933,10 @@ func convertToStandardNotation(ports []string) ([]string, error) {
 func parseLoggingOpts(loggingDriver string, loggingOpts []string) (map[string]string, error) {
 	loggingOptsMap := opts.ConvertKVStringsToMap(loggingOpts)
 	if loggingDriver == "none" && len(loggingOpts) > 0 {
-		return map[string]string{}, fmt.Errorf("invalid logging opts for driver %s", loggingDriver)
+		return map[string]string{}, hint.Wrap(
+			errors.New("log driver \"none\" accepts no --log-opt entries"),
+			"Remove the --log-opt flag(s) or choose a different --log-driver.",
+		)
 	}
 	return loggingOptsMap, nil
 }
@@ -984,7 +1000,7 @@ func parseStorageOpts(storageOpts []string) (map[string]string, error) {
 	for _, option := range storageOpts {
 		k, v, ok := strings.Cut(option, "=")
 		if !ok {
-			return nil, errors.New("invalid storage option")
+			return nil, fmt.Errorf("invalid --storage-opt value %q: expected key=value", option)
 		}
 		m[k] = v
 	}
@@ -1095,12 +1111,12 @@ func validateLinuxPath(val string, validator func(string) bool) (string, error)
 	var mode string
 
 	if strings.Count(val, ":") > 2 {
-		return val, fmt.Errorf("bad format for path: %s", val)
+		return val, fmt.Errorf("invalid --device %q: too many ':' separators, expected [host-path:]container-path[:mode]", val)
 	}
 
 	split := strings.SplitN(val, ":", 3)
 	if split[0] == "" {
-		return val, fmt.Errorf("bad format for path: %s", val)
+		return val, fmt.Errorf("invalid --device %q: host path before ':' is empty, expected [host-path:]container-path[:mode]", val)
 	}
 	switch len(split) {
 	case 1:

cli/command/container/opts_test.go

@@ -767,7 +767,7 @@ func TestParseModes(t *testing.T) {
 	args := []string{"--pid=container:", "img", "cmd"}
 	assert.NilError(t, flags.Parse(args))
 	_, err := parse(flags, copts, runtime.GOOS)
-	assert.ErrorContains(t, err, "--pid: invalid PID mode")
+	assert.ErrorContains(t, err, "invalid --pid mode")
 
 	// pid ok
 	_, hostconfig, _, err := parseRun([]string{"--pid=host", "img", "cmd"})
@@ -778,7 +778,7 @@ func TestParseModes(t *testing.T) {
 
 	// uts ko
 	_, _, _, err = parseRun([]string{"--uts=container:", "img", "cmd"}) //nolint:dogsled
-	assert.ErrorContains(t, err, "--uts: invalid UTS mode")
+	assert.ErrorContains(t, err, "invalid --uts mode")
 
 	// uts ok
 	_, hostconfig, _, err = parseRun([]string{"--uts=host", "img", "cmd"})
@@ -923,8 +923,8 @@ func TestParseHealth(t *testing.T) {
 
 func TestParseLoggingOpts(t *testing.T) {
 	// logging opts ko
-	if _, _, _, err := parseRun([]string{"--log-driver=none", "--log-opt=anything", "img", "cmd"}); err == nil || err.Error() != "invalid logging opts for driver none" {
-		t.Fatalf("Expected an error with message 'invalid logging opts for driver none', got %v", err)
+	if _, _, _, err := parseRun([]string{"--log-driver=none", "--log-opt=anything", "img", "cmd"}); err == nil || !strings.HasPrefix(err.Error(), "log driver \"none\" accepts no --log-opt entries") {
+		t.Fatalf("Expected an error stating that 'none' accepts no --log-opt entries, got %v", err)
 	}
 	// logging opts ok
 	_, hostconfig, _, err := parseRun([]string{"--log-driver=syslog", "--log-opt=something", "img", "cmd"})
@@ -1034,22 +1034,24 @@ func TestValidateDevice(t *testing.T) {
 		"/hostPath:/containerPath:rw",
 		"/hostPath:/containerPath:mrw",
 	}
+	const emptyHostMsg = `: host path before ':' is empty, expected [host-path:]container-path[:mode]`
+	const tooManyMsg = `: too many ':' separators, expected [host-path:]container-path[:mode]`
 	invalid := map[string]string{
-		"":        "bad format for path: ",
+		"":        `invalid --device ""` + emptyHostMsg,
 		"./":      "./ is not an absolute path",
 		"../":     "../ is not an absolute path",
 		"/:../":   "../ is not an absolute path",
 		"/:path":  "path is not an absolute path",
-		":":       "bad format for path: :",
+		":":       `invalid --device ":"` + emptyHostMsg,
 		"/tmp:":   " is not an absolute path",
-		":test":   "bad format for path: :test",
-		":/test":  "bad format for path: :/test",
+		":test":   `invalid --device ":test"` + emptyHostMsg,
+		":/test":  `invalid --device ":/test"` + emptyHostMsg,
 		"tmp:":    " is not an absolute path",
-		":test:":  "bad format for path: :test:",
-		"::":      "bad format for path: ::",
-		":::":     "bad format for path: :::",
-		"/tmp:::": "bad format for path: /tmp:::",
-		":/tmp::": "bad format for path: :/tmp::",
+		":test:":  `invalid --device ":test:"` + emptyHostMsg,
+		"::":      `invalid --device "::"` + emptyHostMsg,
+		":::":     `invalid --device ":::"` + tooManyMsg,
+		"/tmp:::": `invalid --device "/tmp:::"` + tooManyMsg,
+		":/tmp::": `invalid --device ":/tmp::"` + tooManyMsg,
 		"path:ro": "ro is not an absolute path",
 		"path:rr": "rr is not an absolute path",
 		"a:/b:ro": "bad mode specified: ro",

cli/command/container/update.go

@@ -9,6 +9,7 @@ import (
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/command/completion"
+	"github.com/docker/cli/internal/hint"
 	"github.com/docker/cli/opts"
 	containertypes "github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/client"
@@ -92,7 +93,10 @@ func runUpdate(ctx context.Context, dockerCli command.Cli, options *updateOption
 	var err error
 
 	if options.nFlag == 0 {
-		return errors.New("you must provide one or more flags when using this command")
+		return hint.Wrap(
+			errors.New("no resource flags supplied — nothing to update"),
+			"Pass at least one tunable flag (for example --memory, --cpus, --restart). Run 'docker container update --help' for the full list.",
+		)
 	}
 
 	var restartPolicy containertypes.RestartPolicy