docker/cli · error

top-level object must be a mapping

Error message

top-level object must be a mapping

What it means

Error "top-level object must be a mapping" thrown in docker/cli.

Source

Thrown at cli/compose/loader/loader.go:69

	return volumespec.Parse(spec)
}

// WithDiscardEnvFiles sets the Options to discard the `env_file` section after resolving to
// the `environment` section
func WithDiscardEnvFiles(options *Options) {
	options.discardEnvFiles = true
}

// ParseYAML reads the bytes from a file, parses the bytes into a mapping
// structure, and returns it.
func ParseYAML(source []byte) (map[string]any, error) {
	var cfg any
	if err := yaml.Unmarshal(source, &cfg); err != nil {
		return nil, err
	}
	_, ok := cfg.(map[string]any)
	if !ok {
		return nil, errors.New("top-level object must be a mapping")
	}
	converted, err := convertToStringKeysRecursive(cfg, "")
	if err != nil {
		return nil, err
	}
	return converted.(map[string]any), nil
}

// Load reads a ConfigDetails and returns a fully loaded configuration
func Load(configDetails types.ConfigDetails, opt ...func(*Options)) (*types.Config, error) {
	if len(configDetails.ConfigFiles) < 1 {
		return nil, errors.New("no files specified")
	}

	options := &Options{
		Interpolate: &interp.Options{
			Substitute:      template.Substitute,
			LookupValue:     configDetails.LookupEnv,

View on GitHub (pinned to e9452d6e78)

When it happens

Trigger: Thrown at cli/compose/loader/loader.go:69 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/4b6f3790a135aa22.json. Report an issue: GitHub.