What causes "builder '%s' release failed" in hyperledger/fabric?

Run bin/release manually with the same bld/release dir arguments to see the root cause

builder '%s' release failed

Error message

builder '%s' release failed

What it means

The external builder's release script exited non-zero. The script bin/release was found via LookPath and run with the build and release dirs, and its failure aborts the release phase for this chaincode.

Source

Thrown at core/container/externalbuilder/externalbuilder.go:328

	}

	return nil
}

// Release runs the `release` script.
func (b *Builder) Release(buildContext *BuildContext) error {
	release := filepath.Join(b.Location, "bin", "release")

	_, err := exec.LookPath(release)
	if err != nil {
		b.Logger.Debugf("Skipping release step for '%s' as no release binary found", buildContext.CCID)
		return nil
	}

	cmd := b.NewCommand(release, buildContext.BldDir, buildContext.ReleaseDir)
	err = b.runCommand(cmd)
	if err != nil {
		return errors.Wrapf(err, "builder '%s' release failed", b.Name)
	}

	return nil
}

// runConfig is serialized to disk when launching.
type runConfig struct {
	CCID        string `json:"chaincode_id"`
	PeerAddress string `json:"peer_address"`
	ClientCert  string `json:"client_cert"` // PEM encoded client certificate
	ClientKey   string `json:"client_key"`  // PEM encoded client key
	RootCert    string `json:"root_cert"`   // PEM encoded peer chaincode certificate
	MSPID       string `json:"mspid"`
}

func newRunConfig(ccid string, peerConnection *ccintf.PeerConnection, mspid string) runConfig {
	var tlsConfig ccintf.TLSConfig
	if peerConnection.TLSConfig != nil {

View on GitHub (pinned to 2736b63f8f)

Solutions

Run bin/release manually with the same bld/release dir arguments to see the root cause
Ensure bin/release exists and is executable
Check the release directory is writable and has free disk space; fix the script

Example fix

// before
#!/bin/sh
cp $3/connection.json $2
// after
#!/bin/sh
set -eu
cp "$1/connection.json" "$2/connection.json"

Defensive patterns

Strategy: try-catch

Validate before calling

releaseBin := filepath.Join(builderPath, "bin", "release")
if info, err := os.Stat(releaseBin); err != nil || info.Mode()&0o111 == 0 {
    return fmt.Errorf("builder %s missing executable bin/release", builderPath)
}

Try / catch

err := builder.Release(ctx)
if err != nil {
    log.Errorf("release failed: %v; check %s writes connection.json to release dir", err, releaseDir)
}

Prevention

Verify the release script produces connection.json in the release dir during testing
Ensure the peer process has write access to the release directory
Use set -eu in release scripts to fail fast with a clear failing line

When it happens

Trigger: Builder.Release() runs <builder>/bin/release with BldDir and ReleaseDir arguments; the script returns non-zero, is missing, or is not executable.

Common situations: Release script cannot write connection.json to the release directory (permissions/disk full); script has a bug; builder only supports chaincode-as-a-service and release steps misconfigured.

Related errors

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