What causes "--format is not yet supported with --tree" in docker/cli?

Drop --format when using --tree

--format is not yet supported with --tree

Error message

--format is not yet supported with --tree

What it means

Fourth check in shouldUseTree(): the `--tree` view has its own fixed layout and does not honor a custom Go template via --format, so passing both is rejected to avoid silently ignoring the user's template.

Solutions

Drop --format when using --tree
Use --format with the tabular view (no --tree) for custom output
Use the default tree layout or a separate formatted invocation

Example fix

// before
docker images --tree --format '{{json .}}'
// after
docker images --format '{{json .}}'

Defensive patterns

Strategy: validation

Validate before calling

if options.tree && options.format != "" {
    return errors.New("--format is not supported with --tree")
}

Prevention

Do not pass a custom --format with --tree
Use --format with the tabular view for templated output
Keep format strings in a variable and omit them for tree invocations

When it happens

Trigger: `docker images --tree --format '{{json .}}'` or any custom format string with --tree.

Common situations: A standardized --format used across all image commands conflicts with the tree renderer; templating scripts applied uniformly.

Related errors

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

Appendix: source

Thrown at cli/command/image/list.go:170

			return false, errors.New("--quiet is not yet supported with --tree")
		}
		return false, nil
	}
	if options.noTrunc {
		if options.tree {
			return false, errors.New("--no-trunc is not yet supported with --tree")
		}
		return false, nil
	}
	if options.showDigests {
		if options.tree {
			return false, errors.New("--show-digest is not yet supported with --tree")
		}
		return false, nil
	}
	if options.format != "" {
		if options.tree {
			return false, errors.New("--format is not yet supported with --tree")
		}
		return false, nil
	}
	return true, nil
}

// isDangling is a copy of [formatter.isDangling].
func isDangling(img image.Summary) bool {
	if len(img.RepoTags) == 0 {
		return true
	}
	return len(img.RepoTags) == 1 && img.RepoTags[0] == "<none>:<none>" && len(img.RepoDigests) == 1 && img.RepoDigests[0] == "<none>@<none>"
}

// printAmbiguousHint prints an informational warning if the provided filter
// argument is ambiguous.
//
// The "docker images" top-level subcommand predates the "docker <object> <verb>"

View on GitHub (pinned to 4f84911bfe)