hyperledger/fabric · error

docker image build failed

Error message

docker image build failed

What it means

Thrown by DockerVM.Build when vm.buildImage fails, i.e. the Docker daemon rejected or failed the image build after GenerateDockerBuild succeeded. buildImage issues a docker ImageBuild (with PullParent, NetworkMode etc.) and returns any error the daemon streams back. It means the platform builder produced a context but the docker build itself (compile, base image pull, Dockerfile steps) failed.

Source

Thrown at core/container/dockercontroller/dockercontroller.go:162

	imageName, err := vm.GetVMNameForDocker(ccid)
	if err != nil {
		return nil, err
	}

	// This is an awkward translation, but better here in a future dead path
	// than elsewhere.  The old enum types are capital, but at least as implemented
	// lifecycle tools seem to allow type to be set lower case.
	ccType := strings.ToUpper(metadata.Type)

	_, err = vm.Client.ImageInspect(context.Background(), imageName)
	if err != nil && strings.Contains(err.Error(), "No such image") {
		dockerfileReader, err := vm.PlatformBuilder.GenerateDockerBuild(ccType, metadata.Path, codePackage)
		if err != nil {
			return nil, errors.Wrap(err, "platform builder failed")
		}
		err = vm.buildImage(ccid, dockerfileReader)
		if err != nil {
			return nil, errors.Wrap(err, "docker image build failed")
		}
	} else if err != nil {
		return nil, errors.Wrap(err, "docker image inspection failed")
	}

	return &ContainerInstance{
		DockerVM: vm,
		CCID:     ccid,
		Type:     ccType,
	}, nil
}

// In order to support starting chaincode containers built with Fabric v1.4 and earlier,
// we must check for the precense of the start.sh script for Node.js chaincode before
// attempting to call it.
var nodeStartScript = `
set -e
if [ -x /chaincode/start.sh ]; then

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Read the peer log line 'Error building image: %s' — the wrapped daemon output names the failing Dockerfile step, then fix that step (e.g. fix compile errors in the chaincode source).
2. Ensure the base chaincode image (fabric-ccenv) can be pulled: check network/registry access or set CORE_CHAINCODE_EXECUTETIMEOUT/pull settings appropriately.
3. Free disk space on the Docker daemon host and prune stale images/build cache (docker system prune).
4. Verify docker daemon reachability from the peer (DOCKER_HOST, docker socket mount) and retry the chaincode deploy.

Example fix

// before: build fails behind proxy
//   docker build has no internet to fetch modules
// after: configure proxy for the docker daemon
//   /etc/docker/daemon.json or systemd override:
Environment="HTTP_PROXY=http://proxy:3128" "HTTPS_PROXY=http://proxy:3128"

cli, _ := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if _, err := cli.Ping(context.Background()); err != nil {
	return fmt.Errorf("docker daemon unreachable before chaincode build: %w", err)
}
// also check disk space on the daemon host before building

func isDockerAvailable(ctx context.Context, cli *client.Client) bool {
	_, err := cli.Ping(ctx)
	return err == nil
}

var inst container.Instance
var err error
for i := 0; i < 3; i++ {
	inst, err = vm.Build(ccid, meta, codePackage)
	if err == nil || !strings.Contains(err.Error(), "docker image build failed") {
		break
	}
	time.Sleep(2*time.Second << i) // transient daemon/network issues
}

When it happens

Trigger: Calling Build when the generated Dockerfile's build steps fail: base image cannot be pulled (no network / registry unreachable), chaincode compilation fails inside the container, the docker daemon is out of disk, or build-time options (NetworkMode, ChaincodePull) are invalid.

Common situations: Chaincode that does not compile (Go module resolution failures due to no network access during build); firewalled environments blocking Docker Hub pulls of fabric-ccenv; daemon out of disk space; Docker daemon restarted or unavailable mid-build.

Related errors

• platform builder failed
• Error executing build: %s "%s"
• Error waiting for container to complete: %s
• Error returned from build: %d "%s"
• Error downloading output: %s

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