{"id":"f2c05399d01d2d44","repo":"docker/cli","slug":"you-cannot-restore-multiple-containers-at-once","errorCode":null,"errorMessage":"you cannot restore multiple containers at once","messagePattern":"you cannot restore multiple containers at once","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/start.go","lineNumber":186,"sourceCode":"\t\t\t\t_, _ = fmt.Fprintln(dockerCli.Err(), \"Error monitoring TTY size:\", err)\n\t\t\t}\n\t\t}\n\t\tif attachErr := <-cErr; attachErr != nil {\n\t\t\tvar escapeError term.EscapeError\n\t\t\tif errors.As(attachErr, &escapeError) {\n\t\t\t\t// The user entered the detach escape sequence.\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\treturn attachErr\n\t\t}\n\n\t\tif status := <-statusChan; status != 0 {\n\t\t\treturn cli.StatusError{StatusCode: status}\n\t\t}\n\t\treturn nil\n\tcase opts.Checkpoint != \"\":\n\t\tif len(opts.Containers) > 1 {\n\t\t\treturn errors.New(\"you cannot restore multiple containers at once\")\n\t\t}\n\t\tctr := opts.Containers[0]\n\t\t_, err := dockerCli.Client().ContainerStart(ctx, ctr, client.ContainerStartOptions{\n\t\t\tCheckpointID:  opts.Checkpoint,\n\t\t\tCheckpointDir: opts.CheckpointDir,\n\t\t})\n\t\treturn err\n\tdefault:\n\t\t// We're not going to attach to anything.\n\t\t// Start as many containers as we want.\n\t\treturn startContainersWithoutAttachments(ctx, dockerCli, opts.Containers)\n\t}\n}\n\nfunc startContainersWithoutAttachments(ctx context.Context, dockerCli command.Cli, containers []string) error {\n\tvar failedContainers []string\n\tfor _, ctr := range containers {\n\t\tif _, err := dockerCli.Client().ContainerStart(ctx, ctr, client.ContainerStartOptions{}); err != nil {","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/container/start.go#L168-L204","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Restore one container per command: docker start --checkpoint chk1 ctr1, then docker start --checkpoint chk2 ctr2","Loop in the shell for bulk restore: for c in ctr1 ctr2; do docker start --checkpoint chk-$c $c; done","Verify the daemon has experimental features enabled, since checkpoint/restore requires it"],"exampleFix":"# before\ndocker start --checkpoint snap1 ctr1 ctr2\n# after\ndocker start --checkpoint snap1 ctr1\ndocker start --checkpoint snap1 ctr2","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","container","checkpoint","criu","experimental"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}