hyperledger/fabric · error

docker image inspection failed

Error message

docker image inspection failed

What it means

Thrown by DockerVM.Build when vm.Client.ImageInspect returns an error that does NOT contain 'No such image'. Build treats 'No such image' as the normal 'must build' path; any other inspect error (daemon unreachable, permission denied, malformed image name, context canceled) is wrapped here. It means the peer could not even determine whether the chaincode image exists.

Source

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

	}

	// 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
	/chaincode/start.sh --peer.address %[1]s
else
	cd /usr/local/src

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify the Docker daemon is running and reachable: docker ps from inside the peer's environment; fix DOCKER_HOST or mount /var/run/docker.sock into the peer container.
2. Fix socket permissions (add peer user to docker group, or adjust SELinux label with :z on the volume mount).
3. Check the wrapped error text in the peer log for the precise daemon error and address it (DNS, TLS, timeout).
4. Retry the chaincode build after the daemon recovers; the inspect probe is transient-state sensitive.

Example fix

// before: peer cannot reach docker
docker run hyperledger/fabric-peer ...  # no docker socket mounted
// after
docker run -v /var/run/docker.sock:/var/run/docker.sock hyperledger/fabric-peer ...

cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
	return fmt.Errorf("docker client init failed: %w", err)
}
if _, err := cli.Info(context.Background()); err != nil {
	return fmt.Errorf("docker daemon not inspectable: %w", err)
}

func isNoSuchImage(err error) bool {
	return err != nil && strings.Contains(err.Error(), "No such image")
}

inst, err := vm.Build(ccid, meta, codePackage)
if err != nil {
	if strings.Contains(err.Error(), "docker image inspection failed") {
		// daemon connectivity/permission problem — check DOCKER_HOST,
		// socket mount, and permissions before retrying
	}
	return err
}

When it happens

Trigger: Calling Build when the Docker daemon is down or restarting; the docker socket is not accessible (permission denied); the image name produced by GetVMNameForDocker is rejected; or the inspect request is canceled/times out.

Common situations: Peer container without the docker socket mounted (/var/run/docker.sock missing) → 'Cannot connect to the Docker daemon'; SELinux/permission issues on the socket; DOCKER_HOST pointing to an unreachable daemon; transient daemon unavailability during node restart.

Related errors

• Value of File: was nil
• id cannot be nil if buf is not nil
• depspec cannot be nil if buf is not nil
• nil data bytes
• platform builder failed

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