docker/compose · error

'compose' is not a valid provider type

Error message

'compose' is not a valid provider type

What it means

Compose services can delegate lifecycle to an external provider plugin via `provider:`. 'compose' itself is the built-in engine, not a plugin, so getPluginBinaryPath refuses it: you cannot launch compose-through-compose. Any other provider name is looked up as an installed CLI plugin or an executable on PATH.

Source

Thrown at pkg/compose/plugins.go:194

	err = cmd.Wait()
	if err != nil {
		s.events.On(errorEvent(service.Name, err.Error()))
		return pluginVariables{}, fmt.Errorf("failed to %s service provider: %s", action, err.Error())
	}
	switch command {
	case "up":
		s.events.On(createdEvent(service.Name))
	case "down":
		s.events.On(removedEvent(service.Name))
	case "stop":
		s.events.On(stoppedEvent(service.Name))
	}
	return variables, nil
}

func (s *composeService) getPluginBinaryPath(provider string) (path string, err error) {
	if provider == "compose" {
		return "", errors.New("'compose' is not a valid provider type")
	}
	plugin, err := manager.GetPlugin(provider, s.dockerCli, &cobra.Command{})
	if err == nil {
		path = plugin.Path
	}
	if errdefs.IsNotFound(err) {
		path, err = exec.LookPath(executable(provider))
	}
	return path, err
}

func (s *composeService) setupPluginCommand(ctx context.Context, project *types.Project, service types.ServiceConfig, path, command string) (*exec.Cmd, error) {
	cmdOptionsMetadata := s.getPluginMetadata(path, service.Provider.Type, project)
	var currentCommandMetadata CommandMetadata
	switch command {
	case "up":
		currentCommandMetadata = cmdOptionsMetadata.Up
	case "down":

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Remove the `provider: compose` line — the default (built-in) engine needs no provider key
2. If you meant Kubernetes, use `provider: kube` with the compose-kubernetes plugin installed
3. Use a real plugin name registered with `docker info` plugins list

Example fix

# before
services:
  web:
    provider: compose
    image: nginx
# after
services:
  web:
    image: nginx

python3 - <<'EOF'
import yaml,sys
cfg=yaml.safe_load(open('compose.yaml'))
for n,s in (cfg.get('services') or {}).items():
    if s.get('provider') == 'compose': sys.exit(f"service {n}: provider 'compose' is invalid; remove it")
print('ok')
EOF

When it happens

Trigger: A service in the compose file declares `provider: compose`; during up/start Compose resolves the provider binary and immediately fails for the literal value 'compose'.

Common situations: Setting provider: compose believing it selects the default engine (it is unnecessary — omit provider to use the built-in engine); templating that injects a provider variable defaulting to 'compose'; experimenting with the provider model.

Related errors

• required parameter %q is missing from provider %q definition
• healthcheck.start_interval requires healthcheck.start_period
• your Compose stack cannot be published as it only contains a
• watch rules MUST define a path
• service %q build configuration does not support platform: %s

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