What causes "Docker Compose does not support configs.*.driver" in docker/compose?

Remove the `driver:` key from the config declaration and provide the config as `file:` or `content:` instead

Docker Compose does not support configs.*.driver

Error message

Docker Compose does not support configs.*.driver

What it means

When creating containers, Compose materializes top-level `configs` as bind-mount files. Configs declared with a `driver:` rely on SwarmKit driver plugins to produce secret data, which plain Docker Compose (non-Swarm) cannot do, so creation aborts with an explicit 'not supported' error rather than silently mounting nothing.

Source

Thrown at pkg/compose/create.go:1173

func buildContainerConfigMounts(p types.Project, s types.ServiceConfig) ([]mount.Mount, error) {
	mounts := map[string]mount.Mount{}

	configsBaseDir := "/"
	for _, config := range s.Configs {
		target := config.Target
		if config.Target == "" {
			target = configsBaseDir + config.Source
		} else if !isAbsTarget(config.Target) {
			target = configsBaseDir + config.Target
		}

		definedConfig := p.Configs[config.Source]
		if definedConfig.External {
			return nil, fmt.Errorf("unsupported external config %s", definedConfig.Name)
		}

		if definedConfig.Driver != "" {
			return nil, errors.New("Docker Compose does not support configs.*.driver") //nolint:staticcheck
		}
		if definedConfig.TemplateDriver != "" {
			return nil, errors.New("Docker Compose does not support configs.*.template_driver") //nolint:staticcheck
		}

		if definedConfig.Environment != "" || definedConfig.Content != "" {
			continue
		}

		if config.UID != "" || config.GID != "" || config.Mode != nil {
			logrus.Warn("config `uid`, `gid` and `mode` are not supported, they will be ignored")
		}

		bindMount, err := buildMount(p, types.ServiceVolumeConfig{
			Type:     types.VolumeTypeBind,
			Source:   definedConfig.File,
			Target:   target,
			ReadOnly: true,

View on GitHub (pinned to ddc4b044b6)

Solutions

Remove the `driver:` key from the config declaration and provide the config as `file:` or `content:` instead
If you need driver-backed configs, deploy with `docker stack deploy` (Swarm) instead of compose up
Use `profiles:` to gate Swarm-only services out of compose runs

Example fix

# before
configs:
  cert:
    driver: my-driver
# after
configs:
  cert:
    file: ./cert.pem

Defensive patterns

Strategy: validation

Validate before calling

#!/bin/sh
# fail if any top-level config declares a Swarm-only driver
if grep -qE '^  [a-zA-Z0-9._-]+:.*driver:' docker-compose.yml 2>/dev/null; then :; fi
python3 - <<'EOF'
import yaml,sys
cfg=yaml.safe_load(open('compose.yaml'))
for n,c in (cfg.get('configs') or {}).items():
    if 'driver' in c: sys.exit(f"config {n} uses unsupported driver")
EOF

Prevention

Lint compose files with a schema-aware linter (docker compose config) before up
Keep Swarm stack files separate from compose dev files

When it happens

Trigger: A compose file with a top-level configs entry containing `driver: <name>` (e.g. driver: secretfiles), used by a service, when `docker compose up` (or the create API) resolves configs.

Common situations: Reusing a docker-stack.yml / Swarm service file with compose up; configs declared with driver opts for CSI-style plugins; migrating from Swarm to Compose without stripping driver-based configs.

Related errors

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