docker/compose · error

Docker Compose does not support secrets.*.driver

Error message

Docker Compose does not support secrets.*.driver

What it means

Secrets in Compose are delivered as plain files mounted under /run/secrets; a `driver:` on a secret means 'generate this secret with a SwarmKit driver plugin', which Compose cannot execute. Container creation therefore fails loudly instead of mounting an empty or bogus secret.

Source

Thrown at pkg/compose/create.go:1223

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

	secretsDir := "/run/secrets/"
	for _, secret := range s.Secrets {
		target := secret.Target
		if secret.Target == "" {
			target = secretsDir + secret.Source
		} else if !isAbsTarget(secret.Target) {
			target = secretsDir + secret.Target
		}

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

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

		if definedSecret.Environment != "" {
			continue
		}

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

		if _, err := os.Stat(definedSecret.File); os.IsNotExist(err) {
			logrus.Warnf("secret file %s does not exist", definedSecret.Name)
		}

		mnt, err := buildMount(p, types.ServiceVolumeConfig{

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Replace the driver-backed secret with `file:` or `environment:` delivery
2. Use `external: true` with the secret pre-created if you manage secrets out-of-band
3. Deploy with `docker stack deploy` if driver plugins are required

Example fix

# before
secrets:
  db-password:
    driver: vault
# after
secrets:
  db-password:
    file: ./secrets/db-password

python3 - <<'EOF'
import yaml,sys
cfg=yaml.safe_load(open('compose.yaml'))
for n,s in (cfg.get('secrets') or {}).items():
    if 'driver' in s: sys.exit(f"secret {n} uses unsupported driver")
print('ok')
EOF

When it happens

Trigger: A top-level secrets entry with `driver:` (e.g. driver: vault) referenced by a service, hit during `docker compose up`/create.

Common situations: Swarm stack files with driver-backed secrets used locally; evaluating Swarm-oriented secret plugins (Vault/AWS secrets drivers) under compose; copy-pasting production Swarm config into a dev compose file.

Related errors

• Docker Compose does not support secrets.*.template_driver
• Docker Compose does not support configs.*.driver
• Docker Compose does not support configs.*.template_driver
• unsupported external secret %s
• cannot publish compose file with local includes

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