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.

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 be stopped
• instance has not yet been built, cannot get chaincode…
• could not find handler
• block deliverer for channel
• block deliverer for channel

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

Appendix: 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)