hyperledger/fabric · error

instance was not successfully started

Error message

instance was not successfully started

What it means

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.

Source

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

	i.Session.Signal(syscall.SIGTERM)
	select {
	case <-time.After(i.TermTimeout):
		i.Session.Signal(syscall.SIGKILL)
	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

1. Only call Wait after Start() returns nil error (which sets Session).
2. Check inst.Session != nil before waiting, or track a started flag in your own code.
3. If Start failed, handle its error instead of calling Wait to learn the exit status.

Example fix

// before
inst.Start()
exitCode, err := inst.Wait()
// after
if err := inst.Start(); err != nil {
    return fmt.Errorf("start failed: %w", err)
}
exitCode, err := inst.Wait()

if inst.Session == nil {
    return errors.New("cannot wait: instance never started")
}
code, err := inst.Wait()

func canWait(i *externalbuilder.Instance) bool {
    return i != nil && i.Session != nil
}

When it happens

Trigger: Calling Wait() (directly, or via Stop's internal Wait goroutine) on an Instance whose Start() was never called or failed, leaving Session nil.

Common situations: 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.

Related errors

• instance has not been started
• panic(err)
• config ID illegal, cannot be empty
• config ID illegal, cannot be longer than %d
• name '%s' for config ID is not allowed

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