hyperledger/fabric · error

instance has not yet been built, cannot be started

Error message

instance has not yet been built, cannot be started

What it means

Returned by container Instance.Start when Start is called on an instance whose Build step never completed (or was not invoked). The runtime contract requires build-then-start; starting an unbuilt instance is rejected by this guard.

Source

Thrown at core/container/container.go:52

	Build(ccid string, metadata []byte, codePackageStream io.Reader) (Instance, error)
}

//go:generate counterfeiter -o mock/instance.go --fake-name Instance . Instance

// 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 {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Call Build successfully before calling Start
2. Check the Build error path — the failed build was likely swallowed
3. For external builders, verify the build script exited 0

When it happens

Trigger: Thrown at core/container/container.go:52 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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