{"record":{"id":"33af3e1f9d8ff216","repo":"hyperledger/fabric","slug":"timeout-expired-while-starting-chaincode-s-for-tr","errorCode":null,"errorMessage":"timeout expired while starting chaincode %s for transaction","messagePattern":"timeout expired while starting chaincode (.+?) for transaction","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/chaincode/runtime_launcher.go","lineNumber":130,"sourceCode":"\t\t\t\treturn\n\t\t\t}\n\t\t\texitCode, err := r.Runtime.Wait(ccid)\n\t\t\tif err != nil {\n\t\t\t\tlaunchState.Notify(errors.Wrap(err, \"failed to wait on container exit\"))\n\t\t\t}\n\t\t\tlaunchState.Notify(errors.Errorf(\"container exited with %d\", exitCode))\n\t\t}()\n\t}\n\n\tvar err error\n\tselect {\n\tcase <-launchState.Done():\n\t\terr = errors.WithMessage(launchState.Err(), \"chaincode registration failed\")\n\tcase err = <-startFailCh:\n\t\tlaunchState.Notify(err)\n\t\tr.Metrics.LaunchFailures.With(\"chaincode\", ccid).Add(1)\n\tcase <-timeoutCh:\n\t\terr = errors.Errorf(\"timeout expired while starting chaincode %s for transaction\", ccid)\n\t\tlaunchState.Notify(err)\n\t\tr.Metrics.LaunchTimeouts.With(\"chaincode\", ccid).Add(1)\n\t}\n\n\tsuccess := true\n\tif err != nil && !alreadyStarted {\n\t\tsuccess = false\n\t\tchaincodeLogger.Debugf(\"stopping due to error while launching: %+v\", err)\n\t\tdefer r.Registry.Deregister(ccid)\n\t}\n\n\tr.Metrics.LaunchDuration.With(\n\t\t\"chaincode\", ccid,\n\t\t\"success\", strconv.FormatBool(success),\n\t).Observe(time.Since(startTime).Seconds())\n\n\tchaincodeLogger.Debug(\"launch complete\")\n\treturn err","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/chaincode/runtime_launcher.go#L112-L148","documentation":"The peer waited the configured timeout (core.chaincode.startuptimeout, default 300s) for the chaincode to start and register, and none of the launch outcomes (done/fail) arrived in time. This error aborts the launch and fails the transaction.","triggerScenarios":"The timeoutCh fires in Launch() while waiting for the chaincode to register — no registration, no start failure, no completed launch within the startup timeout window.","commonSituations":"Slow image pull or slow chaincode start on a loaded host; chaincode never registers because it crashed silently; network isolation between peer and chaincode; startup timeout too low for heavy chaincode initialization.","solutions":["Increase chaincode.startuptimeout in the peer's core.yaml (e.g., 600s)","Check chaincode container/peer logs to see why registration didn't happen in time","Ensure the chaincode registers promptly (call shim.Start/shim.ChaincodeServer immediately at boot)","Reduce host load or speed up image pulls (pre-pull images, local registry)"],"exampleFix":"// before\nchaincode:\n  startuptimeout: 300s\n// after\nchaincode:\n  startuptimeout: 600s","handlingStrategy":"retry","validationCode":"// pre-check chaincode image/local binary is present and fast to start\nexec.Command(\"docker\", \"image\", \"inspect\", ccImage).Run() // must succeed","typeGuard":null,"tryCatchPattern":"if err := launcher.Launch(ccid); err != nil && strings.Contains(err.Error(), \"timeout expired while starting chaincode\") {\n    time.Sleep(5 * time.Second)\n    // check chaincode logs, possibly increase startuptimeout, then retry\n}","preventionTips":["Raise chaincode.startuptimeout for slow-starting chaincode","Pre-pull container images on peer hosts","Make chaincode register immediately at process start","Alert on peer/chaincode startup latency"],"tags":["timeout","chaincode","configuration"],"backgroundTag":"chaincode-startup-timeout","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"}