hyperledger/fabric · error

instance has not yet been built, cannot wait

Error message

instance has not yet been built, cannot wait

What it means

UninitializedInstance.Wait is the placeholder implementation: Wait blocks for a built container's exit code, and since no instance was ever built there is nothing to wait on. The call always returns this error.

Source

Thrown at core/container/container.go:64

	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
	mutex           sync.Mutex
}

func (r *Router) getInstance(ccid string) Instance {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Fix the earlier build failure so a real instance is registered, then Wait will function.
2. Rebuild/redeploy the chaincode package to replace the placeholder instance.
3. Check peer logs for 'no DockerBuilder, cannot build' or external-builder errors preceding this, and fix that root cause.

Example fix

// before
exitCode, err := instance.Wait()

// after: verify the instance was built before waiting
if _, err := instance.ChaincodeServerInfo(); err != nil {
	return errors.WithMessage(err, "chaincode not built, cannot wait")
}
exitCode, err := instance.Wait()

// only wait on instances that actually built
if _, err := instance.ChaincodeServerInfo(); err != nil {
	return errors.WithMessage(err, "instance not built; skip Wait")
}

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

exitCode, err := instance.Wait()
if err != nil {
	if strings.Contains(err.Error(), "not yet been built") {
		return rebuildAndWait(ccid) // rebuild then wait
	}
	return err
}

When it happens

Trigger: Calling Wait() on an Instance whose underlying type is UninitializedInstance — e.g. the peer's handler waits for chaincode termination for a chaincode whose build never produced a real instance.

Common situations: Chaincode launch failed silently earlier (no DockerBuilder, external builder produced nothing) and later lifecycle code waits on the instance exit; legacy docker path used while Docker is disabled.

Related errors

• instance has not yet been built, cannot get chaincode server
• instance has not yet been built, cannot be stopped
• 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/84dce33dcb6b46f0. Report an issue: GitHub.