docker/compose · error · api.ErrNotFound

no container found for project %q: %w

Error message

no container found for project %q: %w

What it means

projectFromName reconstructs a types.Project from actually existing Docker resources labeled for the project. When the container list passed in is empty it cannot build any service set, so it returns the project together with an error wrapping api.ErrNotFound. This powers commands that operate on existing state (e.g. images, ps-based flows) rather than the Compose file.

Source

Thrown at pkg/compose/compose.go:365

func getContainerNameWithoutProject(c container.Summary) string {
	project := c.Labels[api.ProjectLabel]
	defaultName := getDefaultContainerName(project, c.Labels[api.ServiceLabel], c.Labels[api.ContainerNumberLabel])
	name := getCanonicalContainerName(c)
	if name != defaultName {
		// service declares a custom container_name
		return name
	}
	return name[len(project)+1:]
}

// projectFromName builds a types.Project based on actual resources with compose labels set
func (s *composeService) projectFromName(containers Containers, projectName string, services ...string) (*types.Project, error) {
	project := &types.Project{
		Name:     projectName,
		Services: types.Services{},
	}
	if len(containers) == 0 {
		return project, fmt.Errorf("no container found for project %q: %w", projectName, api.ErrNotFound)
	}
	set := types.Services{}
	for _, c := range containers {
		serviceLabel, ok := c.Labels[api.ServiceLabel]
		if !ok {
			serviceLabel = getCanonicalContainerName(c)
		}
		service, ok := set[serviceLabel]
		if !ok {
			service = types.ServiceConfig{
				Name:   serviceLabel,
				Image:  c.Image,
				Labels: c.Labels,
			}
		}
		service.Scale = increment(service.Scale)
		set[serviceLabel] = service
	}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Start the project first: `docker compose up -d`, then re-run the failing command
2. Verify the project name matches what's running: `docker compose ls` and `docker ps --filter label=com.docker.compose.project
3. If containers were removed unexpectedly, check `docker compose ps -a` and `docker events` for prune/down activity

Example fix

# before
docker compose exec web sh        # no containers yet

# after
docker compose up -d
docker compose exec web sh

containers, err := composeAPI.ListContainers(ctx, projectName, nil) // equivalent listing call
if err == nil && len(containers) == 0 {
    return fmt.Errorf("project %q has no containers; run up first", projectName)
}

if err := op(ctx, project, ...); err != nil && errors.Is(err, api.ErrNotFound) {
    // treat as 'not started yet': run up -d, then retry once
}

When it happens

Trigger: Invoking compose API functions that derive the project from runtime state (projectFromName) when no containers carrying the project label exist — e.g. `docker compose images`/`restart`/`exec` before `up`, after `down`, or against a mistyped project name (`-p`).

Common situations: Running lifecycle commands in a fresh checkout without `up` first; scripts chaining `up -d && exec` where up failed silently; wrong project name because COMPOSE_PROJECT_NAME differs from the directory; containers removed by `down` or pruned.

Related errors

• no such service: %q: %w
• service %q is not running container #%d
• no container(s) found with the following name(s): %s
• not found
• deleting paths in %s: %w

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