[RFC] errors: introduce structured hints + apply audit-driven rewrites

[dvdksn]

What I did

Two things, packaged together so the abstraction is motivated by concrete improvements rather than argued in the abstract:

1. Introduces internal/hint — a small (~50-line) package that attaches actionable user guidance to errors. The hint is exposed via a Hinter interface, walked out of the error chain by the top-level renderer in cmd/docker/docker.go, and printed on its own line. Hints are not part of err.Error(), so substring assertions on error messages stay stable as hints are added or reworded.

2. Applies 31 error-message rewrites flagged by an end-to-end audit of CLI error quality across 11 command areas. The rewrites are 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 (e.g. image load claiming "stdin is empty" when the actual guard checks IsTerminal(); image list referencing the internal field name --show-digest instead of the user-facing --digests flag; inspect calling template execution failures "parsing errors").
   • Partial success surfaced — operations that succeeded with a follow-up failure now say so, preventing wasted retries (container create cidfile write; image build aux-message decode and missing image ID for --iidfile).
   • Refusal reasons explained — TTY-refusal messages for binary tar output now state why instead of using "cowardly".
   • Echo-the-value / name-the-flag — validation errors include what the user typed and the expected form (the --pid/--uts/--userns/--cgroupns family, --device, --storage-opt, --driver-opt, --subnet, etc.).
   • Internal jargon replaced — container exec's "exec ID empty" (an internal API field) replaced with daemon-anomaly framing.
   • Cause preserved — manifest push ErrBlobCreated now wrapped via %w and described correctly.

How I did it

The mechanism. A 50-line internal package + a 4-line addition to the top-level error renderer. Usage:

return hint.Wrap(
    fmt.Errorf("invalid --pid mode %q", val),
    "Valid forms are 'host' or 'container:<name|id>'.",
)

The cmd/docker renderer walks the chain via errors.As for any Hinter and prints the hint after the error. Errors without a hint are unaffected — the migration is fully incremental, no flag day.

The rewrites. Driven by an audit over the user-facing error inventory (215 errors across container, image, network, volume, context, system, registry, manifest, builder, inspect). Review flagged 32 entries as needing improvement; rewrite produced 31 rewrites + 1 keep-original; an editorial pass approved 29 outright and flagged 3 for cross-entry consistency tweaks (which are folded in).

15 of the rewrites have an explicit hint and use hint.Wrap; the rest are message-only changes.

How to verify

• make test — the test suite is updated where assertions referenced the old wordings.
• Manually trigger a few of the rewritten errors:

  docker image save alpine               # writes to terminal -> binary-tar refusal with reason + hint
  docker image load                       # stdin is a TTY -> states the actual condition + hint
  docker run --pid=hsot alpine            # echoes the bad value + lists valid forms
  docker network create --subnet=10.0.0.0/24 --subnet=10.0.0.128/25 net  # names both overlapping subnets
  docker volume update some-non-cluster-volume  # names the volume + the constraint
  

• Compare err.Error() to substring-based test expectations to confirm hints are not part of the message string (they render on their own line).

Why internal-only

Keeps API surface small while we iterate. If buildx/compose/scout adopt the same Hinter interface independently, errors flowing through docker CLI's renderer Just Work via duck-typing — they don't need to import the same package, just match the interface shape. Promotion to public is a rename when the convention proves out.

Out of scope (intentional)

• withHelp in container/run.go still uses \n\n for its --help suggestion. Pre-existing pattern, untouched in this PR — natural follow-up to migrate to hint.Wrap once the mechanism lands.
• Stderr-write error sites (18 per the inventory). They bypass the central renderer entirely; addressing them needs separate consolidation work.
• Catalog / identity-based error matching (à la sentinel var ErrFoo = ... patterns). The current shape is a strict subset of what a catalog would provide; if it's wanted later, Wrap can sit underneath without breaking call sites.
• One known nit deferred — context create's "no docker endpoint configured: set one with --docker, or copy from an existing context with --from" reads slightly off because --docker takes a structured key=value value rather than a single thing to "set". Happy to refine if reviewers prefer different wording.

Related

• Feature request: better error message for 'docker create network' and other similar incorrect patterns #1986 — broader feature request for better error messages around docker create network and similar; this PR doesn't close it but addresses the pattern.
• The [RFC] framing in the title follows the convention of [RFC] standardise exit-codes #1683 (standardise exit-codes) — small enough abstraction that splitting RFC-doc and implementation would feel ceremonial, but big enough to want maintainer sign-off on the approach before going through detailed review.

Asks of reviewers

Marked as draft intentionally. Before deep-diving on each individual rewrite, I'd appreciate feedback on:

1. Is internal/hint the right shape? Or would you rather see it inlined into cli/error.go next to StatusError, or a different abstraction entirely?
2. The hint.Wrap(err, "hint") vs \n\n<hint> migration boundary — should this PR also migrate withHelp, or is keeping that as a follow-up clearer?
3. Any rewrites I shouldn't have shipped — the audit's bar was "concrete user-visible benefit", but reviewers closer to specific commands may have context I missed (e.g. manifest/push's ErrBlobCreated wording uses domain terms that may or may not be appropriate).

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

❌ Patch coverage is 56.25000% with 42 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cli/command/container/opts.go	52.17%	11 Missing ⚠️
cli/command/container/create.go	0.00%	4 Missing ⚠️
cli/command/container/export.go	20.00%	4 Missing ⚠️
cli/command/container/update.go	0.00%	4 Missing ⚠️
cli/command/context/export.go	0.00%	4 Missing ⚠️
cli/command/manifest/push.go	0.00%	4 Missing ⚠️
cli/command/image/build.go	0.00%	3 Missing ⚠️
cmd/docker/docker.go	0.00%	2 Missing ⚠️
cli/command/context/create.go	0.00%	1 Missing ⚠️
cli/command/context/options.go	0.00%	1 Missing ⚠️
... and 4 more

📢 Thoughts on this report? Let us know!

[vvoland]

I like this!

I think it might be a little bit more complicated to implement this properly though 😿

[vvoland]

This will be swallowed by cli.StatusError wrapping at the call site:

cli/cli/command/container/create.go

Line 124 in 3f81d71

Status: withHelp(err, "create").Error(),

[vvoland]

This will also be case for many other operations too

[vvoland]

Ideally, we'd probably also want the plugins to be able to return hintable errors:

cli/cli-plugins/plugin/plugin.go

Line 110 in 3f81d71

_, _ = fmt.Fprintln(dockerCLI.Err(), err)

[vvoland]

This could be just:

Suggested change

	// Of returns the first non-empty hint in the error chain, or "" if
	// none of the wrapped errors implement [Hinter].
	func Of(err error) string {
	for err != nil {
	if h, ok := err.(Hinter); ok {
	if msg := h.Hint(); msg != "" {
	return msg
	}
	}
	err = errors.Unwrap(err)
	}
	return ""
	}
	// Of returns the first non-empty hint in the error chain, or "" if
	// none of the wrapped errors implement [Hinter].
	func Of(err error) string {
	var h Hinter
	if errors.As(err, &h) {
	return h.Hint()
	}
	return ""
	}

and perhaps we don't even need this func at all then?