required parameter %q is missing from provider %q definition

Error message

required parameter %q is missing from provider %q definition

What it means

Before invoking a service provider plugin, compose validates the provider's options against the command's parameter metadata. Any parameter marked Required must appear in the provider definition's options map; the first missing one aborts with its name and the provider type.

Source

Thrown at pkg/compose/plugins.go:317

	Required    bool   `json:"required"`
	Type        string `json:"type"`
	Default     string `json:"default,omitempty"`
}

func (c CommandMetadata) GetParameter(paramName string) (ParameterMetadata, bool) {
	for _, p := range c.Parameters {
		if p.Name == paramName {
			return p, true
		}
	}
	return ParameterMetadata{}, false
}

func (c CommandMetadata) CheckRequiredParameters(provider types.ServiceProviderConfig) error {
	for _, p := range c.Parameters {
		if p.Required {
			if _, ok := provider.Options[p.Name]; !ok {
				return fmt.Errorf("required parameter %q is missing from provider %q definition", p.Name, provider.Type)
			}
		}
	}
	return nil
}

// firstLine returns the first line of s, stripping any trailing newlines.
func firstLine(s string) string {
	s = strings.TrimRight(s, "\n")
	if before, _, ok := strings.Cut(s, "\n"); ok {
		return before
	}
	return s
}

View on GitHub (pinned to ddc4b044b6)

Solutions

Read the provider's parameter list (docker compose provider docs or plugin metadata) to find required options
Add the missing option under the provider's options in the compose file
After adding, re-run docker compose config to confirm validation passes

Example fix

# before
services:
  db:
    provider:
      type: nebius-postgres

# after
services:
  db:
    provider:
      type: nebius-postgres
      options:
        username: admin
        password: {{ env_required("DB_PASSWORD") }}

Defensive patterns

Strategy: validation

Validate before calling

// before up: run config validation which exercises CheckRequiredParameters
if err := project.Validate(os.Getenv); err != nil {
    return err // names the missing required parameter
}

Try / catch

if err := compose.Up(ctx, project, opts); err != nil {
    if strings.Contains(err.Error(), "required parameter") {
        // parse parameter name from message and add it to provider options
    }
}

Prevention

Run docker compose config as a CI gate for every compose file using providers
Document required provider options next to each provider type in your repo

When it happens

Trigger: Declaring a service with provider: type X but omitting an option that X's metadata marks required — e.g. a database provider demanding 'password' — then running docker compose up.

Common situations: Copy-pasted provider examples with placeholders removed; providers whose required set grew in a new version; assuming defaults exist for required parameters.

Related errors

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