hyperledger/fabric · error

Failed to pull %s: %s

Error message

Failed to pull %s: %s

What it means

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.

Source

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

	if opts.Image == "" {
		opts.Image = GetDockerImageFromConfig("chaincode.builder")
		if opts.Image == "" {
			return fmt.Errorf("No image provided and \"chaincode.builder\" default does not exist")
		}
	}

	logger.Debugf("Attempting build with options: %s", opts)

	// -----------------------------------------------------------------------------------
	// Ensure the image exists locally, or pull it from a registry if it doesn't
	// -----------------------------------------------------------------------------------
	_, err := client.ImageInspect(context.Background(), opts.Image)
	if err != nil {
		logger.Debugf("Image %s does not exist locally, attempt pull", opts.Image)

		ipResp, err := client.ImagePull(context.Background(), opts.Image, dcli.ImagePullOptions{})
		if err != nil {
			return fmt.Errorf("Failed to pull %s: %s", opts.Image, err)
		}
		err = ipResp.Wait(context.Background())
		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,
		},

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Pre-pull the builder image manually (docker pull <image>) so ImageInspect succeeds
2. Fix the image name/tag referenced by chaincode.builder or opts.Image
3. Configure registry credentials (docker login / auth config) for private registries
4. Check network/DNS connectivity and registry rate limits

Example fix

// before
# no image locally, build fails at runtime
// after
$ docker pull hyperledger/fabric-ccenv:latest
$ # then retry the chaincode build

if _, err := client.ImageInspect(ctx, builderImage); err != nil {
    rc, rerr := client.ImagePull(ctx, builderImage, dcli.ImagePullOptions{})
    if rerr != nil {
        return fmt.Errorf("precheck pull of %s failed: %w", builderImage, rerr)
    }
    rc.Close()
}

if err != nil && strings.HasPrefix(err.Error(), "Failed to pull") {
    // inspect registry connectivity/auth, then retry with backoff
    return retryWithBackoff(func() error { return util.DockerBuild(opts, client) }, 3)
}

When it happens

Trigger: ImageInspect fails (image not local) AND client.ImagePull errors — bad image name/tag, no network, private registry auth missing, or rate limiting.

Common situations: Offline or air-gapped environments, mistyped image tags, Docker Hub rate limits, or private registries without docker login credentials configured on the peer host.

Related errors

• Failed to wait pull %s: %s
• failed to ping to Docker daemon
• failed to create target folder for connection.json: %s
• reading http response body: %s
• could not connect to ordering service

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