unable to start container image

Error message

unable to start container image %v with docker for env %v, err: %w

What it means

After creating the SDK harness container, dockerEnvironment starts it via ContainerStart. If the daemon fails to start the container, the error is wrapped with the image, worker environment, and cause, and the client is closed. This usually means the container was created but could not be run.

Solutions

Run `docker run <image>` manually to reproduce the container start failure
Check `docker logs`/daemon logs for the OCI runtime error
Verify image architecture matches the host (linux/amd64 vs linux/arm64)
Free disk/memory resources and retry the job

Defensive patterns

Strategy: validation

Validate before calling

if err := exec.Command("docker", "run", "--rm", img, "--help").Run(); err != nil {
  return fmt.Errorf("image %s fails to start on this host: %w", img, err)
}

Prevention

Verify image architecture matches the host platform
Ensure adequate disk/memory before starting jobs

When it happens

Trigger: ContainerStart fails: image entrypoint/runtime errors at exec time, port conflicts, insufficient resources, OCI runtime errors, or the container exits immediately.

Common situations: Incompatible image architecture (arm64 image on amd64 host), missing container runtime privileges, out-of-memory/disk conditions, or a corrupted image layer.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/aa0b91c9bc666240. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/runners/prism/internal/environments.go:240

			Tty:   false,
		},
		HostConfig: &container.HostConfig{
			NetworkMode: "host",
			Mounts:      mounts,
			AutoRemove:  true,
		},
	})
	if err != nil {
		cli.Close()
		return fmt.Errorf("unable to create container image %v with docker for env %v, err: %w", dp.GetContainerImage(), wk.Env, err)
	}
	containerID := ccr.ID
	logger = logger.With("container", containerID)

	_, err = cli.ContainerStart(ctx, containerID, dcli.ContainerStartOptions{})
	if err != nil {
		cli.Close()
		return fmt.Errorf("unable to start container image %v with docker for env %v, err: %w", dp.GetContainerImage(), wk.Env, err)
	}

	logger.Debug("container started")
	logger.Debug("container start command", "cmd", cmd)

	// Start goroutine to wait on container state.
	go func() {
		defer cli.Close()
		defer wk.Stop()
		defer func() {
			logger.Debug("container stopped")
		}()

		bgctx := context.Background()

		// Wait for either context cancellation or container to stop
		type waitResult struct {
			err error

View on GitHub (pinned to 12126d8942)