{"record":{"id":"078654aab8c983e7","repo":"hyperledger/fabric","slug":"failed-to-pull-s-s","errorCode":null,"errorMessage":"Failed to pull %s: %s","messagePattern":"Failed to pull (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/chaincode/platforms/util/utils.go","lineNumber":81,"sourceCode":"\tif opts.Image == \"\" {\n\t\topts.Image = GetDockerImageFromConfig(\"chaincode.builder\")\n\t\tif opts.Image == \"\" {\n\t\t\treturn fmt.Errorf(\"No image provided and \\\"chaincode.builder\\\" default does not exist\")\n\t\t}\n\t}\n\n\tlogger.Debugf(\"Attempting build with options: %s\", opts)\n\n\t// -----------------------------------------------------------------------------------\n\t// Ensure the image exists locally, or pull it from a registry if it doesn't\n\t// -----------------------------------------------------------------------------------\n\t_, err := client.ImageInspect(context.Background(), opts.Image)\n\tif err != nil {\n\t\tlogger.Debugf(\"Image %s does not exist locally, attempt pull\", opts.Image)\n\n\t\tipResp, err := client.ImagePull(context.Background(), opts.Image, dcli.ImagePullOptions{})\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to pull %s: %s\", opts.Image, err)\n\t\t}\n\t\terr = ipResp.Wait(context.Background())\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to wait pull %s: %s\", opts.Image, err)\n\t\t}\n\t}\n\n\t// -----------------------------------------------------------------------------------\n\t// Create an ephemeral container, armed with our Image/Cmd\n\t// -----------------------------------------------------------------------------------\n\tcontainer, err := client.ContainerCreate(context.Background(), dcli.ContainerCreateOptions{\n\t\tConfig: &dcontainer.Config{\n\t\t\tAttachStdout: true,\n\t\t\tAttachStderr: true,\n\t\t\tEnv:          opts.Env,\n\t\t\tCmd:          []string{\"/bin/sh\", \"-c\", opts.Cmd},\n\t\t\tImage:        opts.Image,\n\t\t},","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/chaincode/platforms/util/utils.go#L63-L99","documentation":"DockerBuild inspects the builder image locally; if absent it attempts client.ImagePull. This error means the pull from the docker registry failed, so the builder image is neither local nor fetchable. The registry/transport error is embedded in the message.","triggerScenarios":"ImageInspect fails (image not local) AND client.ImagePull errors — bad image name/tag, no network, private registry auth missing, or rate limiting.","commonSituations":"Offline or air-gapped environments, mistyped image tags, Docker Hub rate limits, or private registries without docker login credentials configured on the peer host.","solutions":["Pre-pull the builder image manually (docker pull <image>) so ImageInspect succeeds","Fix the image name/tag referenced by chaincode.builder or opts.Image","Configure registry credentials (docker login / auth config) for private registries","Check network/DNS connectivity and registry rate limits"],"exampleFix":"// before\n# no image locally, build fails at runtime\n// after\n$ docker pull hyperledger/fabric-ccenv:latest\n$ # then retry the chaincode build","handlingStrategy":"retry","validationCode":"if _, err := client.ImageInspect(ctx, builderImage); err != nil {\n    rc, rerr := client.ImagePull(ctx, builderImage, dcli.ImagePullOptions{})\n    if rerr != nil {\n        return fmt.Errorf(\"precheck pull of %s failed: %w\", builderImage, rerr)\n    }\n    rc.Close()\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.HasPrefix(err.Error(), \"Failed to pull\") {\n    // inspect registry connectivity/auth, then retry with backoff\n    return retryWithBackoff(func() error { return util.DockerBuild(opts, client) }, 3)\n}","preventionTips":["Pre-pull the builder image during peer provisioning","Configure registry credentials for private images","Monitor Docker Hub rate limits; use a local mirror/registry","Verify network/DNS from the peer host"],"tags":["docker","network","image-pull","registry"],"backgroundTag":"image-pull-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"}