hyperledger/fabric · error

platform builder failed

Error message

platform builder failed

What it means

Thrown by DockerVM.Build in Hyperledger Fabric's dockercontroller when vm.PlatformBuilder.GenerateDockerBuild fails to produce the Docker build context for a chaincode package. The platform-specific builder (Golang/Node/Java) inspects and rewrites the chaincode source tarball into a Dockerfile tar stream; any failure reading the package, recognizing the chaincode type, or assembling the build context is wrapped here. It means the chaincode image was never attempted to be built because the build input could not be generated.

Source

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

}

// Build is responsible for building an image if it does not already exist.
func (vm *DockerVM) Build(ccid string, metadata *persistence.ChaincodePackageMetadata, codePackage io.Reader) (container.Instance, error) {
	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

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify the chaincode package metadata (Type, Path) matches the actual package contents; repackage the chaincode with the correct --lang and path.
2. Rebuild the chaincode package with the current peer's lifecycle tooling (peer lifecycle chaincode package) so the tar layout is compatible.
3. Enable debug logging on the peer and inspect the wrapped underlying error for the exact platform-builder failure (e.g. missing file, unsupported type).
4. Check that the chaincode language is supported (GOLANG/JAVA/NODE) and that the source path exists inside the package.

Example fix

// before: package created with mismatched lang
peer lifecycle chaincode package cc.tar.gz --path ./src --lang golang --label cc_1  // path wrong, no go sources there
// after
peer lifecycle chaincode package cc.tar.gz --path ./chaincode --lang golang --label cc_1

func validatePackage(meta *persistence.ChaincodePackageMetadata, pkg io.Reader) error {
	if meta == nil || meta.Type == "" || meta.Path == "" {
		return errors.New("chaincode package metadata incomplete")
	}
	switch strings.ToUpper(meta.Type) {
	case "GOLANG", "JAVA", "NODE", "CAR":
	default:
		return fmt.Errorf("unsupported chaincode type: %s", meta.Type)
	}
	return nil
}

func isSupportedType(t string) bool {
	switch strings.ToUpper(t) {
	case "GOLANG", "JAVA", "NODE", "CAR":
		return true
	}
	return false
}

inst, err := vm.Build(ccid, meta, codePackage)
if err != nil {
	if strings.Contains(err.Error(), "platform builder failed") {
		// repackage chaincode or fix metadata.Type/Path, then retry
	}
	return fmt.Errorf("chaincode deploy aborted: %w", err)
}

When it happens

Trigger: Calling Build (or installing/approving a chaincode package which eventually calls it) when: the code package tarball is corrupt or truncated; metadata.Path points to a missing directory inside the package; metadata.Type is not recognized by the platform registry; or the platform builder errors parsing the package contents.

Common situations: Deploying chaincode with a package whose metadata.Type is misspelled or lowercase in a form the builder registry rejects; an empty or malformed package produced by an older peer lifecycle tool; packages built for a different Fabric version whose layout the current platform builder does not expect.

Related errors

• Error executing build: %s "%s"
• Error returned from build: %d "%s"
• docker image build failed
• error writing files to upload to Docker instance into a temp
• Value of File: was nil

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