docker/compose · error

cannot attach to services not included in up: %s

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.

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)

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

# 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[@]}"

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

• --wait cannot be combined with --abort-on-container-exit, --
• --detach cannot be combined with --abort-on-container-exit,
• cannot combine --attach and --attach-dependencies
• --wait-timeout must be a non-negative integer
• --abort-on-container-failure cannot be combined with --abort

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