service %s is required by %s but is disabled. Can be enabled

Error message

service %s is required by %s but is disabled. Can be enabled by profiles %s

What it means

The dependency graph found a 'depends_on' edge to a service that exists in the project but is inactive because no enabling profile is set. Since depends_on defaults to required: true, compose reports which profiles would enable the missing service instead of failing with a plain not-found.

Source

Thrown at pkg/compose/dependencies.go:273

	}

	for _, s := range project.Services {
		graph.AddVertex(s.Name, s.Name, initialStatus)
	}

	for index, s := range project.Services {
		for _, name := range s.GetDependencies() {
			err := graph.AddEdge(s.Name, name)
			if err != nil {
				if !s.DependsOn[name].Required {
					delete(s.DependsOn, name)
					project.Services[index] = s
					continue
				}
				if api.IsNotFoundError(err) {
					ds, err := project.GetDisabledService(name)
					if err == nil {
						return nil, fmt.Errorf("service %s is required by %s but is disabled. Can be enabled by profiles %s", name, s.Name, ds.Profiles)
					}
				}
				return nil, err
			}
		}
	}

	if b, err := graph.HasCycles(); b {
		return nil, err
	}

	return graph, nil
}

// NewVertex is the constructor function for the Vertex
func NewVertex(key string, service string, initialStatus ServiceStatus) *Vertex {
	return &Vertex{
		Key:      key,

View on GitHub (pinned to ddc4b044b6)

Solutions

Enable the profile: COMPOSE_PROFILES=debug docker compose up or docker compose --profile debug up
If the dependency is truly optional, mark it: depends_on: {db: {required: false, condition: service_started}}
Move the service out of profiles if it is always required

Example fix

# before
services:
  db:
    profiles: [debug]
  api:
    depends_on: [db]
# after (optional dep)
services:
  api:
    depends_on:
      db:
        condition: service_started
        required: false

Defensive patterns

Strategy: validation

Validate before calling

// before up: ensure every required dependency is active
disabled, _ := project.GetDisabledService(depName)
if disabled.Name != "" {
    return fmt.Errorf("enable profile(s) %v for %s or mark it optional", disabled.Profiles, depName)
}

Try / catch

if err := compose.Up(...); err != nil && strings.Contains(err.Error(), "is disabled. Can be enabled by profiles") {
    // add the suggested profile and retry
    os.Setenv("COMPOSE_PROFILES", strings.Join(append(profiles, "debug"), ","))
    err = compose.Up(...)
}

Prevention

Export COMPOSE_PROFILES in CI where profile-gated deps are used
Mark optional dependencies required: false
Document profile requirements in the repo README

When it happens

Trigger: services: {api: {depends_on: [db]}}, db has 'profiles: [debug]' but COMPOSE_PROFILES/--profile does not include debug; occurs while building the dependency graph during up/run.

Common situations: Optional services gated behind profiles (debug db, mailhog) referenced by always-on services; forgetting to export COMPOSE_PROFILES in CI; profile renamed but depends_on not updated.

Related errors

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