{"record":{"id":"64b68c99c3d08e33","repo":"hyperledger/fabric","slug":"could-not-launch-chaincode-s","errorCode":null,"errorMessage":"could not launch chaincode %s","messagePattern":"could not launch chaincode (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/chaincode/chaincode_support.go","lineNumber":91,"sourceCode":"\tRuntime                Runtime\n\tTotalQueryLimit        int\n\tUserRunsCC             bool\n\tUseWriteBatch          bool\n\tMaxSizeWriteBatch      uint32\n\tUseGetMultipleKeys     bool\n\tMaxSizeGetMultipleKeys uint32\n}\n\n// Launch starts executing chaincode if it is not already running. This method\n// blocks until the peer side handler gets into ready state or encounters a fatal\n// error. If the chaincode is already running, it simply returns.\nfunc (cs *ChaincodeSupport) Launch(ccid string) (*Handler, error) {\n\tif h := cs.HandlerRegistry.Handler(ccid); h != nil && h.State() == Ready {\n\t\treturn h, nil\n\t}\n\n\tif err := cs.Launcher.Launch(ccid, cs); err != nil {\n\t\treturn nil, errors.Wrapf(err, \"could not launch chaincode %s\", ccid)\n\t}\n\n\th := cs.HandlerRegistry.Handler(ccid)\n\tif h == nil {\n\t\treturn nil, errors.Errorf(\"claimed to start chaincode container for %s but could not find handler\", ccid)\n\t}\n\n\treturn h, nil\n}\n\n// LaunchInProc is a stopgap solution to be called by the inproccontroller to allow system chaincodes to register\nfunc (cs *ChaincodeSupport) LaunchInProc(ccid string) <-chan struct{} {\n\tlaunchStatus, ok := cs.HandlerRegistry.Launching(ccid)\n\tif ok {\n\t\tchaincodeLogger.Panicf(\"attempted to launch a system chaincode which has already been launched\")\n\t}\n\n\treturn launchStatus.Done()","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/chaincode/chaincode_support.go#L73-L109","documentation":"ChaincodeSupport.Launch wraps any failure from the Launcher (cs.Launcher.Launch) when trying to start or connect to a chaincode container for the given ccid. If a handler for the chaincode isn't already in Ready state, the peer attempts to launch the chaincode runtime; any error launching it is wrapped with this message and the ccid. It means the peer could not get a working chaincode container/connection for that chaincode ID.","triggerScenarios":"Calling Execute/ExecuteLegacyInit/Invoke with a chaincode name whose container cannot be started: image not available, package for ccid not installed/committed on the channel, container start fails, or the chaincode fails to register with the peer during launch.","commonSituations":"Chaincode not committed on the channel or invoked with the wrong chaincode name/label; docker daemon down or image pull failure in k8s environments; chaincode container starts but crashes or cannot connect back to the peer (wrong TLS/network config) so Launch times out.","solutions":["Verify the chaincode is correctly installed and committed on the channel, and that the invoked chaincode name/version matches the committed definition.","Check peer logs for the underlying launch error and docker/container logs for the chaincode container to find the root failure (image pull, crash, auth).","Ensure the container runtime (docker daemon or k8s) is healthy and the chaincode image is present/pullable on the node.","Confirm chaincode-to-peer connectivity (peer.chaincode.address, TLS certs) so the launched container can register with the peer."],"exampleFix":"// before: invoking chaincode name that doesn't match the committed definition\npeer chaincode invoke -n wrongcc -c '{\"Args\":[\"init\"]}'\n// after: use the name from the committed definition\npeer chaincode list --committed   # confirm actual name/label\npeer chaincode invoke -n mycc -C mychannel -c '{\"function\":\"init\",\"Args\":[]}'","handlingStrategy":"validation","validationCode":"// Before invoking, verify the chaincode is committed on the channel\npeer chaincode list --committed -C mychannel | grep mycc\n// and that the container runtime is healthy\ndocker info > /dev/null && echo \"docker ok\"","typeGuard":"func IsLaunchFailure(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"could not launch chaincode\")\n}","tryCatchPattern":"err := contract.SubmitTransaction(\"createAsset\", \"a1\")\nif err != nil {\n    if IsLaunchFailure(err) {\n        // check committed definitions and container runtime, then retry after remediation\n        return fmt.Errorf(\"chaincode %s not launchable: %w\", \"mycc\", err)\n    }\n    return err\n}","preventionTips":["Always invoke the exact chaincode name/version from the committed definition.","Confirm the chaincode package is installed and committed before invoking.","Keep docker/k8s runtime healthy and images pre-pulled on nodes.","Validate chaincode TLS/network config matches the peer's chaincode listener."],"tags":["hyperledger-fabric","chaincode","container"],"backgroundTag":"chaincode-launch-failed","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"}