What causes "service %q is not running" in docker/compose?

Confirm state: `docker compose ps -a` — if the service is exited, fix the crash or `docker compose start web`

service %q is not running

Error message

service %q is not running

What it means

getSpecifiedContainer's no-index variant: the ContainerList call with project/service filters returned zero containers, so no container can be picked for the service. Used by operations that need a live container (exec, run-style flows), so a stopped/removed/never-created service fails here rather than later.

Source

Thrown at pkg/compose/containers.go:107

func (s *composeService) getSpecifiedContainer(ctx context.Context, projectName string, oneOff oneOff, all bool, serviceName string, containerIndex int) (container.Summary, error) {
	defaultFilters := getDefaultFilters(projectName, oneOff, serviceName)
	if containerIndex > 0 {
		defaultFilters.Add("label", containerNumberFilter(containerIndex))
	}
	res, err := s.apiClient().ContainerList(ctx, client.ContainerListOptions{
		Filters: defaultFilters,
		All:     all,
	})
	if err != nil {
		return container.Summary{}, err
	}
	containers := res.Items
	if len(containers) < 1 {
		if containerIndex > 0 {
			return container.Summary{}, fmt.Errorf("service %q is not running container #%d", serviceName, containerIndex)
		}
		return container.Summary{}, fmt.Errorf("service %q is not running", serviceName)
	}

	// Sort by container number first, then put one-off containers at the end
	sort.Slice(containers, func(i, j int) bool {
		numberLabelX, _ := strconv.Atoi(containers[i].Labels[api.ContainerNumberLabel])
		numberLabelY, _ := strconv.Atoi(containers[j].Labels[api.ContainerNumberLabel])
		IsOneOffLabelTrueX := containers[i].Labels[api.OneoffLabel] == "True"
		IsOneOffLabelTrueY := containers[j].Labels[api.OneoffLabel] == "True"

		if IsOneOffLabelTrueX || IsOneOffLabelTrueY {
			return !IsOneOffLabelTrueX && IsOneOffLabelTrueY
		}

		return numberLabelX < numberLabelY
	})
	return containers[0], nil
}

View on GitHub (pinned to ddc4b044b6)

Solutions

Confirm state: `docker compose ps -a` — if the service is exited, fix the crash or `docker compose start web`
If missing entirely, create it: `docker compose up -d web`
Verify you're in the right project (directory or -p name) so the label filters match your containers

Example fix

# before
docker compose exec web sh   # service not running

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

Defensive patterns

Strategy: validation

Validate before calling

list, _ := dockerCli.Client().ContainerList(ctx, client.ContainerListOptions{
    All: true,
    Filters: filters.NewArgs(
        filters.Arg("label", "com.docker.compose.project="+project),
        filters.Arg("label", "com.docker.compose.service="+service),
    ),
})
if len(list.Items) == 0 { return fmt.Errorf("service %s not running; run `up -d` first", service) }

Try / catch

if err != nil && strings.Contains(err.Error(), "is not running") {
    // check `compose ps -a`: start or recreate the service, then retry the command
}

Prevention

Chain commands as `docker compose up -d && docker compose exec ...` so failures stop the chain
For crash-looping services, fix the container exit before exec-based debugging

When it happens

Trigger: `docker compose exec web sh` (or any API built on getSpecifiedContainer without an index) when service 'web' has no containers matching the label filters — never created, removed by down/prune, or created but not running and All=false in the listing.

Common situations: Running exec in CI before `up -d` finishes; containers exited due to crash loops so they no longer appear in running-only lists; wrong project directory/name scoping the label filters to another project's containers.

Related errors

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