{"record":{"id":"1409d814a4f9274e","repo":"hyperledger/fabric","slug":"instance-has-not-yet-been-built-cannot-be-stopped","errorCode":null,"errorMessage":"instance has not yet been built, cannot be stopped","messagePattern":"instance has not yet been built, cannot be stopped","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/container/container.go","lineNumber":60,"sourceCode":"type Instance interface {\n\tStart(peerConnection *ccintf.PeerConnection) error\n\tChaincodeServerInfo() (*ccintf.ChaincodeServerInfo, error)\n\tStop() error\n\tWait() (int, error)\n}\n\ntype UninitializedInstance struct{}\n\nfunc (UninitializedInstance) Start(peerConnection *ccintf.PeerConnection) error {\n\treturn errors.Errorf(\"instance has not yet been built, cannot be started\")\n}\n\nfunc (UninitializedInstance) ChaincodeServerInfo() (*ccintf.ChaincodeServerInfo, error) {\n\treturn nil, errors.Errorf(\"instance has not yet been built, cannot get chaincode server info\")\n}\n\nfunc (UninitializedInstance) Stop() error {\n\treturn errors.Errorf(\"instance has not yet been built, cannot be stopped\")\n}\n\nfunc (UninitializedInstance) Wait() (int, error) {\n\treturn 0, errors.Errorf(\"instance has not yet been built, cannot wait\")\n}\n\n//go:generate counterfeiter -o mock/package_provider.go --fake-name PackageProvider . PackageProvider\n\n// PackageProvider gets chaincode packages from the filesystem.\ntype PackageProvider interface {\n\tGetChaincodePackage(packageID string) (md *persistence.ChaincodePackageMetadata, mdBytes []byte, codeStream io.ReadCloser, err error)\n}\n\ntype Router struct {\n\tExternalBuilder ExternalBuilder\n\tDockerBuilder   DockerBuilder\n\tcontainers      map[string]Instance\n\tPackageProvider PackageProvider","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/container/container.go#L42-L78","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Ensure the chaincode builds successfully first (fix the failed build) before attempting lifecycle stop.","Re-install/rebuild the chaincode package so a real instance replaces the placeholder.","Check the peer log for the original build failure that registered UninitializedInstance and fix its root cause.","If this happens on peer startup cleanup, the placeholder is harmless — treat as 'nothing to stop' and skip."],"exampleFix":"// before\nif err := instance.Stop(); err != nil { return err }\n\n// after: tolerate the uninitialized placeholder\nif err := instance.Stop(); err != nil && !strings.Contains(err.Error(), \"not yet been built\") {\n\treturn err\n}","handlingStrategy":"try-catch","validationCode":"// skip stop if the instance was never built\nif _, err := instance.ChaincodeServerInfo(); err != nil && strings.Contains(err.Error(), \"not yet been built\") {\n\treturn nil // nothing to stop\n}","typeGuard":"func canStop(inst container.Instance) bool {\n\t_, err := inst.ChaincodeServerInfo()\n\treturn err == nil\n}","tryCatchPattern":"if err := instance.Stop(); err != nil {\n\tif strings.Contains(err.Error(), \"not yet been built\") {\n\t\tlogger.Debugf(\"chaincode %s never built, nothing to stop\", ccid)\n\t\treturn nil\n\t}\n\treturn err\n}","preventionTips":["Fix build failures before tearing down chaincode so Stop operates on a real instance","Treat 'not yet been built' on Stop as idempotent no-op during cleanup","Keep DockerBuilder/external builders configured consistently across peer restarts"],"tags":["chaincode","lifecycle","hyperledger-fabric","uninitialized"],"backgroundTag":"uninitialized-instance","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}