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

Read the wrapped exec.ExitError's ExitCode() and the builder's stderr/stdout logs to find the underlying build failure.

builder '%s' run failed

Error message

builder '%s' run failed

What it means

Wait wraps any error from Session.Wait() (the underlying exec session wait) with the message "builder '<name>' run failed". This means the builder process ran but terminated abnormally — non-zero exit, signal death, or exec wait failure.

Source

Thrown at core/container/externalbuilder/instance.go:188

	case <-done:
		return nil
	}

	select {
	case <-time.After(5 * time.Second):
		return errors.Errorf("failed to stop instance '%s'", i.PackageID)
	case <-done:
		return nil
	}
}

func (i *Instance) Wait() (int, error) {
	if i.Session == nil {
		return -1, errors.Errorf("instance was not successfully started")
	}

	err := i.Session.Wait()
	err = errors.Wrapf(err, "builder '%s' run failed", i.Builder.Name)
	if exitErr, ok := errors.Cause(err).(*exec.ExitError); ok {
		return exitErr.ExitCode(), err
	}
	return 0, err
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Read the wrapped exec.ExitError's ExitCode() and the builder's stderr/stdout logs to find the underlying build failure.
Run the builder command manually with the same env/args to reproduce and debug the failure.
Fix the chaincode or builder script (missing packages, compile errors, bad toolchain versions).
Check container/host memory limits if the builder is being killed.

Defensive patterns

Strategy: try-catch

Validate before calling

if exitErr, ok := err.(*exec.ExitError); ok {
    logger.Errorf("builder failed with exit code %d", exitErr.ExitCode())
}

Type guard

func isExitError(err error) (*exec.ExitError, bool) {
    var ee *exec.ExitError
    if errors.As(err, &ee) {
        return ee, true
    }
    return nil, false
}

Try / catch

code, err := inst.Wait()
if err != nil {
    var exitErr *exec.ExitError
    if errors.As(err, &exitErr) {
        return fmt.Errorf("builder exited %d: %w", exitErr.ExitCode(), err)
    }
    return err
}

Prevention

Capture and keep builder stdout/stderr for diagnosis.
Validate chaincode compiles in CI with the same builder.
Pin builder toolchain versions and dependency sources.
Set memory/CPU limits high enough for the build step.

When it happens

Trigger: The external builder binary exits with a non-zero exit code, is killed by a signal, or exec's wait fails while Instance.Wait() is collecting it.

Common situations: Builder script fails to compile chaincode (bad Go code, missing deps in vendored modules); builder image/binary missing dependencies; OOM-killer terminating the build; misconfigured builder producing exit code 1.

Related errors

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