docker/compose · error

unsupported format %q

Error message

unsupported format %q

What it means

`docker compose generate` serializes the produced project with either MarshalJSON or MarshalYAML; the format switch's default branch rejects any `--format` value other than `json` or `yaml`.

Source

Thrown at cmd/compose/generate.go:83

	if err != nil {
		return err
	}
	project, err := backend.Generate(ctx, api.GenerateOptions{
		Containers:  containers,
		ProjectName: opts.ProjectName,
	})
	if err != nil {
		return err
	}

	var content []byte
	switch opts.Format {
	case "json":
		content, err = project.MarshalJSON()
	case "yaml":
		content, err = project.MarshalYAML()
	default:
		return fmt.Errorf("unsupported format %q", opts.Format)
	}
	if err != nil {
		return err
	}
	fmt.Println(string(content))

	return nil
}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use `--format json` or `--format yaml` (default is yaml, so you may simply omit the flag).
2. Normalize any variable used for --format to lowercase without whitespace.
3. Post-process the JSON output with jq/yq if you need another format.

Example fix

# before
docker compose generate --format yml web

# after
docker compose generate --format yaml web

# bash
case "${FORMAT:-yaml}" in json|yaml) ;; *) echo "format must be json|yaml" >&2; exit 2;; esac
docker compose generate --format "$FORMAT" "$@"

When it happens

Trigger: Running `docker compose generate --format toml <container>`, a typo like `yml`, or a pass-through variable with unexpected content.

Common situations: Same-family mistake as other --format flags: inconsistent casing (`YAML`), trailing whitespace from variable expansion, or expecting parity with other Docker CLI format values.

Related errors

• unsupported format %q
• --index requires one service to be selected
• cannot combine --attach and --attach-dependencies
• unsupported --progress value %q
• invalid --pull option %q

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/af8722e0b240facf. Report an issue: GitHub.