docker/compose · error

cannot attach to services not included in up

Error message

cannot attach to services not included in up: %s

What it means

Returned during runUp (foreground up) when the user explicitly passed --attach SERVICE and some of those services are not part of the project being started. The code builds a set from upOptions.attach and diffs it against project.ServiceNames(); any name not present in the project produces this error listing the unexpected services. It guards against silently waiting on containers that will never be launched.

Solutions

  1. Remove or fix the listed service names in --attach so all are in `docker compose config --services` output for this exact invocation.
  2. If the service is profile-gated, enable its profile (--profile X or COMPOSE_PROFILES).
  3. Check overlays: ensure the COMPOSE_FILE set that defines the service is loaded.

Example fix

# before
# 'sidecar' not defined in compose.yml
docker compose up --attach sidecar web

# after
docker compose up --attach web
Defensive patterns

Strategy: validation

Validate before calling

# validate --attach names against this run's resolved services
mapfile -t valid < <(docker compose config --services)
for a in "${ATTACH[@]}"; do
  printf '%s\n' "${valid[@]}" | grep -qx "$a" || { echo "unknown attach target: $a" >&2; exit 2; }
done
docker compose up --attach "${ATTACH[@]}"

Prevention

When it happens

Trigger: `docker compose up --attach sidecar web` where 'sidecar' is not defined in compose.yml; attaching to a service filtered out by profiles (service exists in file but inactive in the resolved project); typos in the service name; attaching to a service that only exists in a different COMPOSE_FILE overlay not loaded this run.

Common situations: Multi-service repos where the attach list was written for the full stack but up runs a subset (services arg or profile filtering); renamed services leaving stale attach lists in scripts; typos.

Related errors

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

Appendix: source

Thrown at cmd/compose/up.go:310

		return err
	}

	if upOptions.noStart {
		return backend.Create(ctx, project, create)
	}

	var consumer api.LogConsumer
	var attach []string
	if !upOptions.Detach {
		consumer = formatter.NewLogConsumer(ctx, dockerCli.Out(), dockerCli.Err(), !upOptions.noColor, !upOptions.noPrefix, upOptions.timestamp)

		var attachSet utils.Set[string]
		if len(upOptions.attach) != 0 {
			// services are passed explicitly with --attach, verify they're valid and then use them as-is
			attachSet = utils.NewSet(upOptions.attach...)
			unexpectedSvcs := attachSet.Diff(utils.NewSet(project.ServiceNames()...))
			if len(unexpectedSvcs) != 0 {
				return fmt.Errorf("cannot attach to services not included in up: %s", strings.Join(unexpectedSvcs.Elements(), ", "))
			}
		} else {
			// mark services being launched (and potentially their deps) for attach
			// if they didn't opt-out via Compose YAML
			attachSet = utils.NewSet[string]()
			var dependencyOpt types.DependencyOption = types.IgnoreDependencies
			if upOptions.attachDependencies {
				dependencyOpt = types.IncludeDependencies
			}
			if err := project.ForEachService(services, func(serviceName string, s *types.ServiceConfig) error {
				if s.Attach == nil || *s.Attach {
					attachSet.Add(serviceName)
				}
				return nil
			}, dependencyOpt); err != nil {
				return err
			}
		}

View on GitHub (pinned to ddc4b044b6)