What causes "no containers for project %q" in docker/compose?

Start the project first: docker compose up -d, then run docker compose wait.

no containers for project

Error message

no containers for project %q

What it means

Wait (docker compose wait) lists the project's containers (including one-off ones) and refuses to continue when none exist. There is nothing to wait on for an exit code without at least one created container.

Solutions

Start the project first: docker compose up -d, then run docker compose wait.
Verify the project name matches the running stack (docker compose ls, docker ps --format '{{.Names}}').
Check spelling of services passed to the wait command/WaitOptions.Services.
Recreate removed containers if the stack was torn down accidentally (docker compose up, not just wait).

Example fix

# before
$ docker compose down -v
$ docker compose wait
# Error: no containers for project "myapp"

# after
$ docker compose up -d
$ docker compose wait

Defensive patterns

Strategy: validation

Validate before calling

func projectHasContainers(ctx context.Context, s *composeService, name string, services []string) bool {
	ctrs, err := s.getContainers(ctx, name, oneOffInclude, false, services...)
	return err == nil && len(ctrs) > 0
}

Try / catch

code, err := composeService.Wait(ctx, projectName, opts)
if err != nil {
    if strings.Contains(err.Error(), "no containers for project") {
        // run Up first, then Wait again
    }
    return code, err
}

Prevention

Always Up before Wait in scripts; gate Wait on a successful Up exit code.
Pin COMPOSE_PROJECT_NAME explicitly in automation.
Use docker compose ls to confirm the target project is running.

When it happens

Trigger: Calling docker compose wait on a project that was never brought up, was fully down-removed, or whose remaining services were filtered out by the --services selection passed in WaitOptions.

Common situations: Script running compose wait before compose up; project name mismatch (COMPOSE_PROJECT_NAME pointing at another project); running wait after compose down; selecting a service subset where none of the selected names match running containers.

Related errors

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

Appendix: source

Thrown at pkg/compose/wait.go:35

package compose

import (
	"context"
	"fmt"

	"github.com/moby/moby/client"
	"golang.org/x/sync/errgroup"

	"github.com/docker/compose/v5/pkg/api"
)

func (s *composeService) Wait(ctx context.Context, projectName string, options api.WaitOptions) (int64, error) {
	containers, err := s.getContainers(ctx, projectName, oneOffInclude, false, options.Services...)
	if err != nil {
		return 0, err
	}
	if len(containers) == 0 {
		return 0, fmt.Errorf("no containers for project %q", projectName)
	}

	eg, waitCtx := errgroup.WithContext(ctx)
	var statusCode int64
	for _, ctr := range containers {
		eg.Go(func() error {
			var err error
			res := s.apiClient().ContainerWait(waitCtx, ctr.ID, client.ContainerWaitOptions{})
			select {
			case result := <-res.Result:
				_, _ = fmt.Fprintf(s.stdout(), "container %q exited with status code %d\n", ctr.ID, result.StatusCode)
				statusCode = result.StatusCode
			case err = <-res.Error:
			}
			return err
		})
	}

View on GitHub (pinned to ddc4b044b6)