docker/cli · error

template parsing error

Error message

template parsing error: %w

What it means

Returned by Context.parseFormat (formatter.go:88) when templates.Parse fails on the Go text/template string derived from the user's --format flag. This is a compile-time template error: the syntax is invalid Go template, an unknown function is referenced, or delimiters are mismatched. The error occurs before any data is rendered, so it is purely about the template grammar.

Solutions

1. Validate the template locally with Go: 'go run' a tiny text/template snippet, or test with a simpler field like '--format {{.ID}}'.
2. Check shell quoting - wrap the format in single quotes to prevent shell expansion of braces.
3. Use only functions provided by github.com/docker/cli/templates (json, id, etc.); avoid Sprig-specific helpers.
4. Start from a known-good format (e.g., '{{json .}}') and add complexity incrementally to isolate the syntax error.

Example fix

# before
docker ps --format {{.ID {{.Names}}
# after
docker ps --format '{{.ID}} {{.Names}}'

// Validate a format string parses before running the command.
import "github.com/docker/cli/templates"

func validateFormat(format string) error {
	_, err := templates.Parse(formatter.Format(format).templateString())
	return err
}

if err := cmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "template parsing error") {
		// the format string is syntactically invalid; fix the --format flag
	}
}

When it happens

Trigger: Running any docker command with --format '<invalid template>', e.g., unbalanced actions '{{.ID', referencing a function that is not registered in the templates package, using wrong delimiters, or a stray '}}'. Also triggered by '--format json' variants that are actually custom templates but malformed.

Common situations: Shell-quoting mistakes that mangle the template (missing quotes around braces); using functions available in Go's text/template but not whitelisted by docker/cli/templates; copy-pasting a template that uses Sprig functions (not available here); typos in field accessor chains.

Related errors

• invalid interpolation format for
• failed to parse hook template
• cannot supply extra formatting options to the pretty…
• hook template contains too many messages
• failed to parse hook template: flagValue: no flags found

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

Appendix: source

Thrown at cli/command/formatter/formatter.go:88

// Context contains information required by the formatter to print the output as desired.
type Context struct {
	// Output is the output stream to which the formatted string is written.
	Output io.Writer
	// Format is used to choose raw, table or custom format for the output.
	Format Format
	// Trunc when set to true will truncate the output of certain fields such as Container ID.
	Trunc bool

	// internal element
	header any
	buffer *bytes.Buffer
}

func (c *Context) parseFormat() (*template.Template, error) {
	tmpl, err := templates.Parse(c.Format.templateString())
	if err != nil {
		return nil, fmt.Errorf("template parsing error: %w", err)
	}
	return tmpl, nil
}

func (c *Context) postFormat(tmpl *template.Template, subContext SubContext) {
	out := c.Output
	if out == nil {
		out = io.Discard
	}
	if !c.Format.IsTable() {
		_, _ = c.buffer.WriteTo(out)
		return
	}

	// Write column-headers and rows to the tab-writer buffer, then flush the output.
	tw := tabwriter.NewWriter(out, 10, 1, 3, ' ', 0)
	_ = tmpl.Funcs(templates.HeaderFunctions).Execute(tw, subContext.FullHeader())
	_, _ = tw.Write([]byte{'\n'})

View on GitHub (pinned to 4f84911bfe)