docker/compose · error

unsupported format %q

Error message

unsupported format %q

What it means

The `docker compose config` command only supports serialization of the resolved project to `json` or `yaml`. The format switch in cmd/compose/config.go hits its default branch when opts.Format is anything else, including an unset-but-customized value.

Source

Thrown at cmd/compose/config.go:250

		err := project.CheckContainerNameUnicity()
		if err != nil {
			return nil, err
		}
	}

	if opts.lockImageDigests {
		warnHooksNotLockable(project)
		project = imagesOnly(project)
	}

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

// imagesOnly return project with all attributes removed but service.images and `type: image` volumes
func imagesOnly(project *types.Project) *types.Project {
	digests := types.Services{}
	for name, config := range project.Services {
		service := types.ServiceConfig{
			Image: config.Image,
		}
		for _, vol := range config.Volumes {
			if vol.Type == types.VolumeTypeImage {
				service.Volumes = append(service.Volumes, vol)
			}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use `--format json` or `--format yaml` exactly (note: `yml` is not accepted).
2. If you need TOML or another format, output `--format json` and convert with an external tool such as yq/jq.
3. Validate the variable feeding `--format` in your wrapper script before invoking compose.

Example fix

# before
docker compose config --format yml

# after
docker compose config --format yaml

# bash
case "$FORMAT" in json|yaml) ;; *) echo "--format must be json|yaml, got '$FORMAT'" >&2; exit 2;; esac
docker compose config --format "$FORMAT"

When it happens

Trigger: Running `docker compose config --format toml` (or any string other than json/yaml). Also possible when a wrapper script passes `--format` from an unvalidated variable.

Common situations: Scripts migrating from `docker-compose config` output processing that assume other formats; typos like `--format yml` (the accepted value is `yaml`); automation passing a format flag through without validation.

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/1e046f9c2a9dbf70. Report an issue: GitHub.