unable to create container image

Error message

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

What it means

dockerEnvironment creates the SDK harness container with the configured image, mounts, and endpoint. If the Docker API ContainerCreate call fails, the client is closed and the error is wrapped with the image name, worker environment, and underlying cause. Note the message says "create container image" but it is the container creation step.

Solutions

Pull the image manually (`docker pull <image>`) to see the real pull error
Verify the SDK container image tag matches a published apache/beam SDK image
Authenticate to the private registry (docker login) if using a custom image
Check mounts/credentials: ensure GOOGLE_APPLICATION_CREDENTIALS points to a readable file

Example fix

// before
pyenv = beam.CreateEnvironment("apache/beam_python3.99_sdk:latest")
// after
pyenv = beam.CreateEnvironment("apache/beam_python3.11_sdk:2.60.0")

Defensive patterns

Strategy: validation

Validate before calling

img := "apache/beam_python3.11_sdk:2.60.0"
out, err := exec.Command("docker", "image", "inspect", img).Output()
if err != nil {
  if err := exec.Command("docker", "pull", img).Run(); err != nil {
    return fmt.Errorf("image %s unavailable: %w", img, err)
  }
}

Prevention

Pre-pull SDK harness images before running jobs
Use exact published image tags, not invented versions

When it happens

Trigger: ContainerCreate returns an error: image not present locally and unpullable, invalid mount/config, name conflict, or the daemon rejected the container config.

Common situations: Typo'd or non-existent SDK container image tag, private registry requiring credentials, no network access to pull the image, or GOOGLE_APPLICATION_CREDENTIALS mount path issues.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

		fmt.Sprintf("--provision_endpoint=%v", wk.Endpoint()),
		fmt.Sprintf("--logging_endpoint=%v", wk.Endpoint()),
	}
	ccr, err := cli.ContainerCreate(ctx, dcli.ContainerCreateOptions{
		Config: &container.Config{
			Image: dp.GetContainerImage(),
			Cmd:   cmd,
			Env:   envs,
			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() {

View on GitHub (pinned to 12126d8942)