docker/cli · error

you cannot restore multiple containers at once

Error message

you cannot restore multiple containers at once

What it means

Raised in RunStart for `docker start --checkpoint` when more than one container is given. Checkpoint restore (an experimental CRIU-based feature) starts a container from a saved checkpoint via ContainerStart with a CheckpointID, and the CLI restricts restore to a single container per invocation since one checkpoint maps to one container.

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 e9452d6e78)

Solutions

1. Restore one container per command: docker start --checkpoint chk1 ctr1, then docker start --checkpoint chk2 ctr2
2. Loop in the shell for bulk restore: for c in ctr1 ctr2; do docker start --checkpoint chk-$c $c; done
3. Verify the daemon has experimental features enabled, since checkpoint/restore requires it

Example fix

# before
docker start --checkpoint snap1 ctr1 ctr2
# after
docker start --checkpoint snap1 ctr1
docker start --checkpoint snap1 ctr2

When it happens

Trigger: `docker start --checkpoint chk1 ctr1 ctr2` — opts.Checkpoint non-empty with len(opts.Containers) > 1. Requires an experimental daemon with checkpoint support; the multi-container check fires client-side before any API call.

Common situations: Batch scripts restoring several checkpointed containers in one command; confusing --checkpoint (restore one container) with a bulk restore workflow; experimenting with `docker checkpoint`/CRIU migration flows.

Related errors

• conflicting options: cannot specify both --network-alias and
• valid streams are STDIN, STDOUT and STDERR
• container prune has been cancelled
• containers prune has been cancelled
• conflicting options: cannot specify both --timeout and --tim

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/f2c05399d01d2d44.json. Report an issue: GitHub.