docker/cli · error

failed to merge file

Error message

failed to merge file %s

What it means

Top-level wrapper produced by the Compose merge loop at merge.go:51 when one or more sub-merges (services, volumes, networks, secrets, configs) for an override file failed. The underlying errors are collected with errors.Join and re-joined with this message naming the offending `override.Filename`. The real failures are in the joined chain; this message identifies WHICH file is at fault.

Solutions

1. Read the wrapped error chain (use errors.Is / unwrap the joined errors) to see which section(s) failed (services, volumes, networks, secrets, configs).
2. Open the file named in the message and fix the incompatible structure flagged by the inner error.
3. Run `docker compose config` on each file separately to confirm each parses before merging.
4. Ensure override files only augment, not retype, keys present in the base file.

Example fix

// diagnose the joined chain in Go
if err != nil {
    var joined interface{ Unwrap() []error }
    if errors.As(err, &joined) {
        for _, e := range joined.Unwrap() {
            fmt.Println(e)
        }
    }
}

// Unwrap the joined chain to pinpoint the failing section.
merged, err := loader.merge(configs)
if err != nil {
    var multi interface{ Unwrap() []error }
    if errors.As(err, &multi) {
        for _, e := range multi.Unwrap() {
            log.Println("merge sub-error:", e)
        }
    }
    return err
}

When it happens

Trigger: Returned by `merge()` when at least one of the `errs` slice entries is non-nil after attempting to merge services, volumes, networks, secrets, or configs of an override into the base config. errors.Join(errs...) is non-nil (merge.go:50).

Common situations: An override Compose file (commonly docker-compose.override.yml) redefines a key with an incompatible type, or references structures the merge transformers cannot reconcile. The filename in the message points the developer at the offending file, while the wrapped errors identify the section.

Related errors

• version mismatched between two composefiles
• cannot merge services
• cannot merge volumes
• cannot merge networks
• cannot merge secrets

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

Appendix: source

Thrown at cli/compose/loader/merge.go:51

		if services, err := mergeServices(base.Services, override.Services); err != nil {
			errs = append(errs, fmt.Errorf("cannot merge services: %w", err))
		} else {
			base.Services = services
		}
		if err := mergo.Map(&base.Volumes, &override.Volumes, mergo.WithOverride); err != nil {
			errs = append(errs, fmt.Errorf("cannot merge volumes: %w", err))
		}
		if err := mergo.Map(&base.Networks, &override.Networks, mergo.WithOverride); err != nil {
			errs = append(errs, fmt.Errorf("cannot merge networks: %w", err))
		}
		if err := mergo.Map(&base.Secrets, &override.Secrets, mergo.WithOverride); err != nil {
			errs = append(errs, fmt.Errorf("cannot merge secrets: %w", err))
		}
		if err := mergo.Map(&base.Configs, &override.Configs, mergo.WithOverride); err != nil {
			errs = append(errs, fmt.Errorf("cannot merge configs: %w", err))
		}
		if err := errors.Join(errs...); err != nil {
			return nil, errors.Join(fmt.Errorf("failed to merge file %s", override.Filename), err)
		}
	}
	return base, nil
}

func mergeServices(base, override []types.ServiceConfig) ([]types.ServiceConfig, error) {
	mergeOpts := []func(*mergo.Config){
		mergo.WithAppendSlice,
		mergo.WithOverride,
		mergo.WithTransformers(&specials{m: map[reflect.Type]func(dst, src reflect.Value) error{
			reflect.PointerTo(reflect.TypeFor[types.LoggingConfig]()):        safelyMerge(mergeLoggingConfig),
			reflect.TypeFor[[]types.ServicePortConfig]():                     mergeSlice(toServicePortConfigsMap, toServicePortConfigsSlice),
			reflect.TypeFor[[]types.ServiceSecretConfig]():                   mergeSlice(toServiceSecretConfigsMap, toServiceSecretConfigsSlice),
			reflect.TypeFor[[]types.ServiceConfigObjConfig]():                mergeSlice(toServiceConfigObjConfigsMap, toSServiceConfigObjConfigsSlice),
			reflect.PointerTo(reflect.TypeFor[types.UlimitsConfig]()):        mergeUlimitsConfig,
			reflect.TypeFor[[]types.ServiceVolumeConfig]():                   mergeSlice(toServiceVolumeConfigsMap, toServiceVolumeConfigsSlice),
			reflect.TypeFor[types.ShellCommand]():                            mergeShellCommand,
			reflect.PointerTo(reflect.TypeFor[types.ServiceNetworkConfig]()): mergeServiceNetworkConfig,

View on GitHub (pinned to 4f84911bfe)