What causes "template parsing error: %w" in docker/cli?

Balance every `{{` with `}}` and validate the template locally: `go run` a snippet using text/template.

template parsing error

Error message

template parsing error: %w

What it means

Returned by `NewTemplateInspectorFromString` (inspector.go:60-63) when `templates.Parse(tmplStr)` fails on the `--format` value passed to any `docker inspect`-style command. The format string is compiled as a Go text/template, so any syntax error (unclosed `{{`, bad pipeline, undefined function) produces this. The %w wraps the underlying text/template parse error.

Solutions

Balance every `{{` with `}}` and validate the template locally: `go run` a snippet using text/template.
Use only documented template functions (json, join, lower, etc.) from the docker CLI templates package.
Fall back to the built-in formats: `--format json` or omit --format for default indented output.
Quote the format string in single quotes to prevent shell interpolation of braces.

Example fix

# before
docker inspect --format '{{.Config.Cmd' img
# after
docker inspect --format '{{.Config.Cmd}}' img

Defensive patterns

Strategy: validation

Validate before calling

// pre-validate a Go format template before passing to --format
import "text/template"
if _, err := template.New("f").Parse(formatStr); err != nil {
    return fmt.Errorf("invalid --format template: %w", err)
}

Try / catch

if err := cli.RunInspect(formatStr); err != nil {
    if strings.Contains(err.Error(), "template parsing error") {
        return fmt.Errorf("fix your --format template syntax: %w", err)
    }
    return err
}

Prevention

Test format strings with a tiny Go text/template program first.
Prefer the built-in --format json when unsure.
Single-quote the format string in the shell.

When it happens

Trigger: Running `docker inspect --format '{{.Id' img` (unclosed action), `--format '{{foo .}}'` (undefined function), or any malformed Go template action. Also triggered by stray characters or unescaped braces.

Common situations: Hand-writing a custom format string, copy-paste introducing smart quotes, referencing a helper function that isn't registered in the templates package.

Related errors

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

Appendix: source

Thrown at cli/command/inspect/inspector.go:62

}

// NewTemplateInspectorFromString creates a new TemplateInspector from a string
// which is compiled into a template.
func NewTemplateInspectorFromString(out io.Writer, tmplStr string) (Inspector, error) {
	if out == nil {
		return nil, errors.New("no output stream")
	}
	if tmplStr == "" {
		return NewIndentedInspector(out), nil
	}

	if tmplStr == "json" {
		return NewJSONInspector(out), nil
	}

	tmpl, err := templates.Parse(tmplStr)
	if err != nil {
		return nil, fmt.Errorf("template parsing error: %w", err)
	}
	return NewTemplateInspector(out, tmpl), nil
}

// GetRefFunc is a function which used by Inspect to fetch an object from a
// reference
type GetRefFunc func(ref string) (any, []byte, error)

// Inspect fetches objects by reference using GetRefFunc and writes the json
// representation to the output writer.
func Inspect(out io.Writer, references []string, tmplStr string, getRef GetRefFunc) error {
	if out == nil {
		return errors.New("no output stream")
	}
	inspector, err := NewTemplateInspectorFromString(out, tmplStr)
	if err != nil {
		return cli.StatusError{StatusCode: 64, Status: err.Error()}
	}

View on GitHub (pinned to 4f84911bfe)