{"record":{"id":"6dec897f2b9f6e17","repo":"hyperledger/fabric","slug":"docker-image-build-failed","errorCode":null,"errorMessage":"docker image build failed","messagePattern":"docker image build failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/container/dockercontroller/dockercontroller.go","lineNumber":162,"sourceCode":"\timageName, err := vm.GetVMNameForDocker(ccid)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// This is an awkward translation, but better here in a future dead path\n\t// than elsewhere.  The old enum types are capital, but at least as implemented\n\t// lifecycle tools seem to allow type to be set lower case.\n\tccType := strings.ToUpper(metadata.Type)\n\n\t_, err = vm.Client.ImageInspect(context.Background(), imageName)\n\tif err != nil && strings.Contains(err.Error(), \"No such image\") {\n\t\tdockerfileReader, err := vm.PlatformBuilder.GenerateDockerBuild(ccType, metadata.Path, codePackage)\n\t\tif err != nil {\n\t\t\treturn nil, errors.Wrap(err, \"platform builder failed\")\n\t\t}\n\t\terr = vm.buildImage(ccid, dockerfileReader)\n\t\tif err != nil {\n\t\t\treturn nil, errors.Wrap(err, \"docker image build failed\")\n\t\t}\n\t} else if err != nil {\n\t\treturn nil, errors.Wrap(err, \"docker image inspection failed\")\n\t}\n\n\treturn &ContainerInstance{\n\t\tDockerVM: vm,\n\t\tCCID:     ccid,\n\t\tType:     ccType,\n\t}, nil\n}\n\n// In order to support starting chaincode containers built with Fabric v1.4 and earlier,\n// we must check for the precense of the start.sh script for Node.js chaincode before\n// attempting to call it.\nvar nodeStartScript = `\nset -e\nif [ -x /chaincode/start.sh ]; then","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/container/dockercontroller/dockercontroller.go#L144-L180","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Ensure the base chaincode image (fabric-ccenv) can be pulled: check network/registry access or set CORE_CHAINCODE_EXECUTETIMEOUT/pull settings appropriately.","Free disk space on the Docker daemon host and prune stale images/build cache (docker system prune).","Verify docker daemon reachability from the peer (DOCKER_HOST, docker socket mount) and retry the chaincode deploy."],"exampleFix":"// before: build fails behind proxy\n//   docker build has no internet to fetch modules\n// after: configure proxy for the docker daemon\n//   /etc/docker/daemon.json or systemd override:\nEnvironment=\"HTTP_PROXY=http://proxy:3128\" \"HTTPS_PROXY=http://proxy:3128\"","handlingStrategy":"retry","validationCode":"cli, _ := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())\nif _, err := cli.Ping(context.Background()); err != nil {\n\treturn fmt.Errorf(\"docker daemon unreachable before chaincode build: %w\", err)\n}\n// also check disk space on the daemon host before building","typeGuard":"func isDockerAvailable(ctx context.Context, cli *client.Client) bool {\n\t_, err := cli.Ping(ctx)\n\treturn err == nil\n}","tryCatchPattern":"var inst container.Instance\nvar err error\nfor i := 0; i < 3; i++ {\n\tinst, err = vm.Build(ccid, meta, codePackage)\n\tif err == nil || !strings.Contains(err.Error(), \"docker image build failed\") {\n\t\tbreak\n\t}\n\ttime.Sleep(2*time.Second << i) // transient daemon/network issues\n}","preventionTips":["Ensure fabric-ccenv base image is pre-pulled or reachable (air-gapped: use a local registry).","Keep adequate free disk space on Docker hosts and prune the build cache regularly.","Pre-compile chaincode locally to catch compile errors before deploying."],"tags":["hyperledger-fabric","docker-build","chaincode-build","docker"],"backgroundTag":"docker-image-build-failed","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}