{"record":{"id":"5119e535be894373","repo":"hyperledger/fabric","slug":"builder-s-run-failed-to-start","errorCode":null,"errorMessage":"builder '%s' run failed to start","messagePattern":"builder '(.+?)' run failed to start","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/container/externalbuilder/externalbuilder.go","lineNumber":383,"sourceCode":"\t\treturn nil, errors.WithMessage(err, \"could not create temp run dir\")\n\t}\n\n\trc := newRunConfig(ccid, peerConnection, b.MSPID)\n\tmarshaledRC, err := json.Marshal(rc)\n\tif err != nil {\n\t\treturn nil, errors.WithMessage(err, \"could not marshal run config\")\n\t}\n\n\tif err := os.WriteFile(filepath.Join(launchDir, \"chaincode.json\"), marshaledRC, 0o600); err != nil {\n\t\treturn nil, errors.WithMessage(err, \"could not write root cert\")\n\t}\n\n\trun := filepath.Join(b.Location, \"bin\", \"run\")\n\tcmd := b.NewCommand(run, bldDir, launchDir)\n\tsess, err := Start(b.Logger, cmd, func(error) { os.RemoveAll(launchDir) })\n\tif err != nil {\n\t\tos.RemoveAll(launchDir)\n\t\treturn nil, errors.Wrapf(err, \"builder '%s' run failed to start\", b.Name)\n\t}\n\n\treturn sess, nil\n}\n\n// runCommand runs a command and waits for it to complete.\nfunc (b *Builder) runCommand(cmd *exec.Cmd) error {\n\tsess, err := Start(b.Logger, cmd)\n\tif err != nil {\n\t\treturn err\n\t}\n\treturn sess.Wait()\n}\n\n// NewCommand creates an exec.Cmd that is configured to prune the calling\n// environment down to the environment variables specified in the external\n// builder's PropagateEnvironment and the DefaultPropagateEnvironment.\nfunc (b *Builder) NewCommand(name string, args ...string) *exec.Cmd {","sourceCodeStart":365,"sourceCodeEnd":401,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/container/externalbuilder/externalbuilder.go#L365-L401","documentation":"Returned by externalbuilder Builder.Run when the builder's bin/run process fails to launch (Start error). The launch dir and chaincode.json were prepared, but the external builder executable could not even be started, so session creation failed.","triggerScenarios":"Builder.Run() creates a launchDir, runs <builder>/bin/run <bldDir> <launchDir> via Start; exec fails immediately — binary missing, not executable, fork/exec resource error.","commonSituations":"bin/run missing or lacking executable bit; builder path wrong in core.yaml; too many processes/file descriptors on the host; bad interpreter shebang in the run script.","solutions":["Verify bin/run exists and is executable in the builder path","Check the builder 'path' in externalBuilders config points to the correct location","Inspect the wrapped exec error (shebang, ENOENT, resource limits) and fix accordingly"],"exampleFix":"// before (builder dir)\nbin/build  bin/release\n// after\nbin/build  bin/release  bin/run   # chmod +x bin/run","handlingStrategy":"validation","validationCode":"runBin := filepath.Join(builderPath, \"bin\", \"run\")\nif info, err := os.Stat(runBin); err != nil || info.Mode()&0o111 == 0 {\n    return fmt.Errorf(\"builder %s missing executable bin/run\", builderPath)\n}\nout, err := exec.Command(runBin, \"--help\").CombinedOutput() // optional smoke test\n_ = out; _ = err","typeGuard":null,"tryCatchPattern":"sess, err := builder.Run(bldDir, launchDir)\nif err != nil {\n    log.Errorf(\"run failed to start: %v — check bin/run exists, is executable, and host fd/proc limits\", err)\n}","preventionTips":["Ship bin/run executable in every builder image/release","Validate the builder path in core.yaml exists on the host","Check host ulimits (nproc, nofile) if launches fail under load"],"tags":["external-builder","exec-failure","subprocess","launch"],"backgroundTag":"exec-format-or-not-found","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}