What causes "Error creating container: %s" in hyperledger/fabric?

Confirm the builder image exists (docker images) and re-pull if removed

Error creating container: %s

Error message

Error creating container: %s

What it means

DockerBuild creates an ephemeral container from the builder image with the provided Env and Cmd. This error means client.ContainerCreate failed, so no build container exists. The docker API error (e.g. image missing, invalid config) is embedded in the message.

Source

Thrown at core/chaincode/platforms/util/utils.go:102

		if err != nil {
			return fmt.Errorf("Failed to wait pull %s: %s", opts.Image, err)
		}
	}

	// -----------------------------------------------------------------------------------
	// Create an ephemeral container, armed with our Image/Cmd
	// -----------------------------------------------------------------------------------
	container, err := client.ContainerCreate(context.Background(), dcli.ContainerCreateOptions{
		Config: &dcontainer.Config{
			AttachStdout: true,
			AttachStderr: true,
			Env:          opts.Env,
			Cmd:          []string{"/bin/sh", "-c", opts.Cmd},
			Image:        opts.Image,
		},
	})
	if err != nil {
		return fmt.Errorf("Error creating container: %s", err)
	}
	defer client.ContainerRemove(context.Background(), container.ID, dcli.ContainerRemoveOptions{})

	// -----------------------------------------------------------------------------------
	// Upload our input stream
	// -----------------------------------------------------------------------------------
	_, err = client.CopyToContainer(context.Background(), container.ID, dcli.CopyToContainerOptions{
		DestinationPath:           "/chaincode/input",
		Content:                   opts.InputStream,
		AllowOverwriteDirWithFile: true,
	})
	if err != nil {
		return fmt.Errorf("Error uploading input to container: %s", err)
	}

	// -----------------------------------------------------------------------------------
	// Attach stdout buffer to capture possible compilation errors
	// -----------------------------------------------------------------------------------

View on GitHub (pinned to 2736b63f8f)

Solutions

Confirm the builder image exists (docker images) and re-pull if removed
Check the embedded docker error for the exact create rejection reason
Validate opts.Env/opts.Cmd values are well-formed
Restart/verify the docker daemon and its storage

Defensive patterns

Strategy: validation

Validate before calling

if _, err := client.ImageInspect(ctx, builderImage); err != nil {
    return fmt.Errorf("builder image %s missing before container create", builderImage)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "Error creating container") {
    logger.Errorf("container create failed: %s — check image presence and daemon", err)
    return err
}

Prevention

Prevent image GC/removal while builds are in flight (docker image prune scheduling)
Validate Env/Cmd contents before invoking DockerBuild
Monitor docker daemon health and storage driver status

When it happens

Trigger: ContainerCreate returns an error: builder image not present locally (pull skipped because ImageInspect succeeded earlier then image was removed), invalid Env/Cmd configuration, or daemon rejecting the container config.

Common situations: Image garbage-collected between inspect and create; malformed chaincode.builder image reference; docker daemon under resource pressure or misconfigured storage driver.

Related errors

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/67906e510cb4842f. Report an issue: GitHub.