hyperledger/fabric · error

instance has not yet been built, cannot be stopped

Error message

instance has not yet been built, cannot be stopped

What it means

UninitializedInstance.Stop is the placeholder implementation on the not-yet-built instance: there is no running container to stop, so the call always fails. It indicates the caller is trying to stop a chaincode whose build never produced a real instance.

Source

Thrown at core/container/container.go:60

type Instance interface {
	Start(peerConnection *ccintf.PeerConnection) error
	ChaincodeServerInfo() (*ccintf.ChaincodeServerInfo, error)
	Stop() error
	Wait() (int, error)
}

type UninitializedInstance struct{}

func (UninitializedInstance) Start(peerConnection *ccintf.PeerConnection) error {
	return errors.Errorf("instance has not yet been built, cannot be started")
}

func (UninitializedInstance) ChaincodeServerInfo() (*ccintf.ChaincodeServerInfo, error) {
	return nil, errors.Errorf("instance has not yet been built, cannot get chaincode server info")
}

func (UninitializedInstance) Stop() error {
	return errors.Errorf("instance has not yet been built, cannot be stopped")
}

func (UninitializedInstance) Wait() (int, error) {
	return 0, errors.Errorf("instance has not yet been built, cannot wait")
}

//go:generate counterfeiter -o mock/package_provider.go --fake-name PackageProvider . PackageProvider

// PackageProvider gets chaincode packages from the filesystem.
type PackageProvider interface {
	GetChaincodePackage(packageID string) (md *persistence.ChaincodePackageMetadata, mdBytes []byte, codeStream io.ReadCloser, err error)
}

type Router struct {
	ExternalBuilder ExternalBuilder
	DockerBuilder   DockerBuilder
	containers      map[string]Instance
	PackageProvider PackageProvider

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Ensure the chaincode builds successfully first (fix the failed build) before attempting lifecycle stop.
2. Re-install/rebuild the chaincode package so a real instance replaces the placeholder.
3. Check the peer log for the original build failure that registered UninitializedInstance and fix its root cause.
4. If this happens on peer startup cleanup, the placeholder is harmless — treat as 'nothing to stop' and skip.

Example fix

// before
if err := instance.Stop(); err != nil { return err }

// after: tolerate the uninitialized placeholder
if err := instance.Stop(); err != nil && !strings.Contains(err.Error(), "not yet been built") {
	return err
}

// skip stop if the instance was never built
if _, err := instance.ChaincodeServerInfo(); err != nil && strings.Contains(err.Error(), "not yet been built") {
	return nil // nothing to stop
}

func canStop(inst container.Instance) bool {
	_, err := inst.ChaincodeServerInfo()
	return err == nil
}

if err := instance.Stop(); err != nil {
	if strings.Contains(err.Error(), "not yet been built") {
		logger.Debugf("chaincode %s never built, nothing to stop", ccid)
		return nil
	}
	return err
}

When it happens

Trigger: Calling Stop() on an Instance whose underlying type is UninitializedInstance — typically when terminating or restarting a chaincode that failed to build or was never built (e.g. no DockerBuilder and no external builder produced an instance).

Common situations: Peer shutdown or chaincode terminate path reaching a container entry registered before a failed build; cleanup after an external builder failed; using the legacy docker chaincode path while Docker support is disabled.

Related errors

• instance has not yet been built, cannot get chaincode server
• instance has not yet been built, cannot wait
• could not find handler: %s
• failed listing installed chaincodes
• failed to parse collection config

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