hyperledger/fabric · error

instance has not yet been built, cannot get chaincode server

Error message

instance has not yet been built, cannot get chaincode server info

What it means

UninitializedInstance is the placeholder Instance stored in the BuildRegistry when a chaincode package exists but no build has actually produced a runnable instance. All methods on it fail because the container lifecycle cannot be driven without a real built instance. ChaincodeServerInfo is called by the peer to learn where a chaincode server is listening; since nothing was built, there is no server info to return.

Source

Thrown at core/container/container.go:56

// Instance represents a built chaincode instance, because of the docker legacy, calling this a
// built 'container' would be very misleading, and going forward with the external launcher
// 'image' also seemed inappropriate.  So, the vague 'Instance' is used here.
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 {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Fix the chaincode build so a real Instance is produced (ensure the external builder emits a valid build output, or re-enable the DockerBuilder).
2. Rebuild/redeploy the chaincode package (lifecycle install + approve + commit) so the registry holds a real instance instead of the placeholder.
3. Check peer logs for the earlier build failure that left the UninitializedInstance registered, and correct the underlying build error.
4. Verify peer configuration: if using external builders exclusively, ensure the builder declares the required runtime and the package type matches one of the configured builders.

Example fix

// before: launching against a placeholder instance
info, err := instance.ChaincodeServerInfo() // fails

// after: only use the instance after a successful build
if err := reg.Build(ccid); err != nil {
	return errors.WithMessage(err, "chaincode build failed")
}
info, err := instance.ChaincodeServerInfo()

// ensure the chaincode built before querying server info
if err := registry.Build(ccid); err != nil {
	return errors.WithMessage(err, "chaincode not built")
}

func isBuilt(inst container.Instance) bool {
	_, err := inst.ChaincodeServerInfo()
	return !strings.Contains(fmt.Sprint(err), "not yet been built")
}

info, err := instance.ChaincodeServerInfo()
if err != nil {
	if strings.Contains(err.Error(), "not yet been built") {
		// rebuild first, then retry
		return rebuildChaincode(ccid)
	}
	return err
}

When it happens

Trigger: Calling ChaincodeServerInfo() on an Instance whose registered concrete type is UninitializedInstance, i.e. the chaincode was registered as 'built' via a non-Docker/external build path that produced no instance, or the build step was skipped/failed and the placeholder was still handed to the launcher.

Common situations: External builder configured but produced no bld/folder or no instance; DockerBuilder disabled (core.yaml chaincode.externalBuilders / docker build path removed) while using the legacy docker chaincode path; a build race where the launcher queries before the real build completed.

Related errors

• instance has not yet been built, cannot be stopped
• 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/0a91d09946c7800a. Report an issue: GitHub.