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

Run the builder's bin/build manually with the same arguments to see the underlying error

external builder '%s' failed

Error message

external builder '%s' failed

What it means

The external builder's `bin/build` script exited non-zero (or failed to run) during the build phase. Fabric wraps the underlying exec error with the builder's name so the failing builder is identifiable.

Source

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

	cmd := b.NewCommand(detect, buildContext.SourceDir, buildContext.MetadataDir)

	err := b.runCommand(cmd)
	if err != nil {
		logger.Debugf("builder '%s' detect failed: %s", b.Name, err)
		return false
	}

	return true
}

// Build runs the `build` script.
func (b *Builder) Build(buildContext *BuildContext) error {
	build := filepath.Join(b.Location, "bin", "build")
	cmd := b.NewCommand(build, buildContext.SourceDir, buildContext.MetadataDir, buildContext.BldDir)

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

	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 {

View on GitHub (pinned to 2736b63f8f)

Solutions

Run the builder's bin/build manually with the same arguments to see the underlying error
Ensure bin/build exists and is executable (chmod +x) inside the builder path
Fix the failing step in the build script (dependencies, toolchain, network access)

Example fix

// before
#!/bin/sh
npm build
// after
#!/bin/sh
set -eu
npm run build

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

err := builder.Build(ctx)
var execErr *exec.ExitError
if errors.As(err, &execErr) {
    log.Errorf("builder %s build failed, exit=%d stderr=%s", name, execErr.ExitCode(), captureStderr)
}

Prevention

Smoke-test bin/build manually with sample source/metadata/bld dirs before deploying the builder
Always chmod +x builder scripts and pin shebangs
Pin and pre-pull toolchain dependencies so builds don't rely on network fetches

When it happens

Trigger: Builder.Build() runs <builder>/bin/build with source, metadata, and output dirs; the script returns a non-zero exit status, is missing, or is not executable.

Common situations: Build script has a bug or unhandled dependency (missing docker, go toolchain, network fetch failure); bin/build lacks the executable bit; builder image/tooling version mismatch after upgrade.

Related errors

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