docker/cli · error

cannot attach to a paused container, unpause it first

Error message

cannot attach to a paused container, unpause it first

What it means

Raised by inspectContainerAndCheckState in cli/command/container/attach.go when the target container's State.Paused is true. A paused container has all its processes frozen via the cgroup freezer, so an attached terminal would receive no output and its input would go nowhere; the CLI rejects the attach up front with instructions to unpause.

Source

Thrown at cli/command/container/attach.go:34

)

// AttachOptions group options for `attach` command
type AttachOptions struct {
	NoStdin    bool
	Proxy      bool
	DetachKeys string
}

func inspectContainerAndCheckState(ctx context.Context, apiClient client.APIClient, args string) (*container.InspectResponse, error) {
	c, err := apiClient.ContainerInspect(ctx, args, client.ContainerInspectOptions{})
	if err != nil {
		return nil, err
	}
	if !c.Container.State.Running {
		return nil, errors.New("cannot attach to a stopped container, start it first")
	}
	if c.Container.State.Paused {
		return nil, errors.New("cannot attach to a paused container, unpause it first")
	}
	if c.Container.State.Restarting {
		return nil, errors.New("cannot attach to a restarting container, wait until it is running")
	}

	return &c.Container, nil
}

// newAttachCommand creates a new cobra.Command for `docker attach`
func newAttachCommand(dockerCLI command.Cli) *cobra.Command {
	var opts AttachOptions

	cmd := &cobra.Command{
		Use:   "attach [OPTIONS] CONTAINER",
		Short: "Attach local standard input, output, and error streams to a running container",
		Args:  cli.ExactArgs(1),
		RunE: func(cmd *cobra.Command, args []string) error {
			containerID := args[0]

View on GitHub (pinned to e9452d6e78)

Solutions

1. Unpause the container, then attach: `docker unpause <container> && docker attach <container>`.
2. Confirm the paused state first with `docker ps` (STATUS shows '(Paused)') or `docker inspect -f '{{.State.Paused}}' <container>`.
3. If the pause was intentional (e.g. freezing for a snapshot), finish that operation before attaching.

Example fix

# before
docker attach myapp   # Error: cannot attach to a paused container
# after
docker unpause myapp
docker attach myapp

When it happens

Trigger: `docker attach <container>` against a container previously paused with `docker pause` (or via an orchestrator/tool that pauses containers), where ContainerInspect returns State.Running == true and State.Paused == true.

Common situations: Containers paused by resource-management or checkpoint tooling and forgotten; someone else on a shared host ran `docker pause`; debugging sessions where pause was used to freeze state and the operator later tries to attach without unpausing — `docker ps` shows the container as '(Paused)' which is easy to miss.

Related errors

• cannot attach to a stopped container, start it first
• cannot attach to a restarting container, wait until it is ru
• valid streams are STDIN, STDOUT and STDERR
• you cannot start and attach multiple containers at once
• failed to parse hook template

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