{"record":{"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/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/start.go#L168-L204","documentation":"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.","triggerScenarios":"`docker start --checkpoint cp1 c1 c2` with checkpoint set and len(Containers) > 1.","commonSituations":"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.","solutions":["Restore one container at a time: loop in your script calling `docker start --checkpoint <id> <ctr>` per container.","Ensure exactly one container name follows the command when --checkpoint is set.","Verify each container has the named checkpoint before invoking start."],"exampleFix":"// before\ndocker start --checkpoint cp1 c1 c2\n\n// after\nfor c in c1 c2; do docker start --checkpoint cp1 \"$c\"; done","handlingStrategy":"validation","validationCode":"func validateRestore(checkpoint string, containers []string) error {\n    if checkpoint != \"\" && len(containers) > 1 {\n        return errors.New(\"you cannot restore multiple containers at once\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Loop restore one container at a time with its own --checkpoint id.","Treat checkpoint/restore as per-container; never batch it.","Validate checkpoint existence per container before invoking start."],"tags":["checkpoint","experimental","container","start","restore"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}