docker/cli · error

failed to start containers

Error message

failed to start containers: %s

What it means

Thrown by startContainersWithoutAttachments when one or more containers fail to start in a batch `docker start` call (no --attach). Each failed container is printed to stderr individually, then this aggregate error lists all names that failed.

Solutions

1. Inspect each failed container's logs/events: docker logs <failed>, docker events --filter container=<failed>
2. Re-create containers whose image was removed: docker run ... or docker compose up
3. Resolve port/resource conflicts identified in the per-container stderr lines
4. Start containers one at a time to isolate the first failure

Example fix

# before
docker start app db cache   # one or more fail
# after
docker start app; docker start db; docker start cache   # isolate failures

// Start containers individually to surface the first real cause.
for _, c := range containers {
    if err := cli.ContainerStart(ctx, c, client.ContainerStartOptions{}); err != nil {
        return fmt.Errorf("start %s: %w", c, err)
    }
}

if err := runStart(ctx, cli, opts); err != nil {
    if strings.Contains(err.Error(), "failed to start containers") {
        // inspect each named container's events for root cause
    }
}

When it happens

Trigger: Running `docker start ctr1 ctr2 ctr3` without --attach; one or more ContainerStart API calls return an error. Common daemon-side reasons: image was removed, runtime/OCI error, resource limits, port conflict, mount failure.

Common situations: Batch-starting after a reboot where some containers reference removed images; port conflicts among several containers; out-of-memory; one container's volume mount source missing.

Related errors

• failed to rename container
• you cannot start and attach multiple containers at once
• you cannot restore multiple containers at once
• every ip-range or gateway must have a corresponding subnet
• multiple overlapping subnet configuration is not supported

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/83d7d5b7587dba71. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/container/start.go:213

		// We're not going to attach to anything.
		// Start as many containers as we want.
		return startContainersWithoutAttachments(ctx, dockerCli, opts.Containers)
	}
}

func startContainersWithoutAttachments(ctx context.Context, dockerCli command.Cli, containers []string) error {
	var failedContainers []string
	for _, ctr := range containers {
		if _, err := dockerCli.Client().ContainerStart(ctx, ctr, client.ContainerStartOptions{}); err != nil {
			_, _ = fmt.Fprintln(dockerCli.Err(), err)
			failedContainers = append(failedContainers, ctr)
			continue
		}
		_, _ = fmt.Fprintln(dockerCli.Out(), ctr)
	}

	if len(failedContainers) > 0 {
		return fmt.Errorf("failed to start containers: %s", strings.Join(failedContainers, ", "))
	}
	return nil
}

View on GitHub (pinned to 4f84911bfe)