{"record":{"id":"de7de1e69fcebe05","repo":"hyperledger/fabric","slug":"instance-was-not-successfully-started","errorCode":null,"errorMessage":"instance was not successfully started","messagePattern":"instance was not successfully started","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/container/externalbuilder/instance.go","lineNumber":184,"sourceCode":"\ti.Session.Signal(syscall.SIGTERM)\n\tselect {\n\tcase <-time.After(i.TermTimeout):\n\t\ti.Session.Signal(syscall.SIGKILL)\n\tcase <-done:\n\t\treturn nil\n\t}\n\n\tselect {\n\tcase <-time.After(5 * time.Second):\n\t\treturn errors.Errorf(\"failed to stop instance '%s'\", i.PackageID)\n\tcase <-done:\n\t\treturn nil\n\t}\n}\n\nfunc (i *Instance) Wait() (int, error) {\n\tif i.Session == nil {\n\t\treturn -1, errors.Errorf(\"instance was not successfully started\")\n\t}\n\n\terr := i.Session.Wait()\n\terr = errors.Wrapf(err, \"builder '%s' run failed\", i.Builder.Name)\n\tif exitErr, ok := errors.Cause(err).(*exec.ExitError); ok {\n\t\treturn exitErr.ExitCode(), err\n\t}\n\treturn 0, err\n}\n","sourceCodeStart":166,"sourceCodeEnd":194,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/container/externalbuilder/instance.go#L166-L194","documentation":"Instance.Wait returns this when Session is nil, meaning the instance was never successfully started, so there is no process to wait on. It is the Wait-side counterpart of the Stop guard and returns -1 as the exit code.","triggerScenarios":"Calling Wait() (directly, or via Stop's internal Wait goroutine) on an Instance whose Start() was never called or failed, leaving Session nil.","commonSituations":"Calling Wait on manually constructed Instance values in tests; race between a failed Start and a concurrent Stop/Wait; lifecycle code that always waits on shutdown regardless of start state.","solutions":["Only call Wait after Start() returns nil error (which sets Session).","Check inst.Session != nil before waiting, or track a started flag in your own code.","If Start failed, handle its error instead of calling Wait to learn the exit status."],"exampleFix":"// before\ninst.Start()\nexitCode, err := inst.Wait()\n// after\nif err := inst.Start(); err != nil {\n    return fmt.Errorf(\"start failed: %w\", err)\n}\nexitCode, err := inst.Wait()","handlingStrategy":"validation","validationCode":"if inst.Session == nil {\n    return errors.New(\"cannot wait: instance never started\")\n}\ncode, err := inst.Wait()","typeGuard":"func canWait(i *externalbuilder.Instance) bool {\n    return i != nil && i.Session != nil\n}","tryCatchPattern":null,"preventionTips":["Only call Wait on instances whose Start returned nil error.","Model the lifecycle explicitly (notStarted -> running -> done) in your code.","In tests, always call Start (or a fake) before Wait."],"tags":["lifecycle","process-management","go"],"backgroundTag":"method-called-before-start","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"}