docker/cli · error

you cannot restore multiple containers at once

Error message

you cannot restore multiple containers at once

What it means

Returned by RunStart in the checkpoint-restore branch when --checkpoint is set and more than one container argument is given. Restoring from a checkpoint operates on a single container/checkpoint pair, so the CLI forbids multiple containers here (start.go:184-187). Checkpoint/restore is an experimental, Linux-only feature.

Solutions

1. Restore one container at a time: loop in your script calling `docker start --checkpoint <id> <ctr>` per container.
2. Ensure exactly one container name follows the command when --checkpoint is set.
3. Verify each container has the named checkpoint before invoking start.

Example fix

// before
docker start --checkpoint cp1 c1 c2

// after
for c in c1 c2; do docker start --checkpoint cp1 "$c"; done

func validateRestore(checkpoint string, containers []string) error {
    if checkpoint != "" && len(containers) > 1 {
        return errors.New("you cannot restore multiple containers at once")
    }
    return nil
}

When it happens

Trigger: `docker start --checkpoint cp1 c1 c2` with checkpoint set and len(Containers) > 1.

Common situations: Bulk-restore scripts passing a list while reusing a single --checkpoint id. Misunderstanding that restore is per-container. Typos adding extra args after the checkpoint flag.

Related errors

• you cannot start and attach multiple containers at once
• cannot attach to a stopped container, start it first
• cannot attach to a paused container, unpause it first
• cannot attach to a restarting container, wait until it is…
• conflicting options: --no-pause and --pause cannot be used…

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

Appendix: source

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

				_, _ = fmt.Fprintln(dockerCli.Err(), "Error monitoring TTY size:", err)
			}
		}
		if attachErr := <-cErr; attachErr != nil {
			var escapeError term.EscapeError
			if errors.As(attachErr, &escapeError) {
				// The user entered the detach escape sequence.
				return nil
			}
			return attachErr
		}

		if status := <-statusChan; status != 0 {
			return cli.StatusError{StatusCode: status}
		}
		return nil
	case opts.Checkpoint != "":
		if len(opts.Containers) > 1 {
			return errors.New("you cannot restore multiple containers at once")
		}
		ctr := opts.Containers[0]
		_, err := dockerCli.Client().ContainerStart(ctx, ctr, client.ContainerStartOptions{
			CheckpointID:  opts.Checkpoint,
			CheckpointDir: opts.CheckpointDir,
		})
		return err
	default:
		// 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 {

View on GitHub (pinned to 4f84911bfe)