timeout expired while starting chaincode %s for transaction

Error message

timeout expired while starting chaincode %s for transaction

What it means

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.

Source

Thrown at core/chaincode/runtime_launcher.go:130

				return
			}
			exitCode, err := r.Runtime.Wait(ccid)
			if err != nil {
				launchState.Notify(errors.Wrap(err, "failed to wait on container exit"))
			}
			launchState.Notify(errors.Errorf("container exited with %d", exitCode))
		}()
	}

	var err error
	select {
	case <-launchState.Done():
		err = errors.WithMessage(launchState.Err(), "chaincode registration failed")
	case err = <-startFailCh:
		launchState.Notify(err)
		r.Metrics.LaunchFailures.With("chaincode", ccid).Add(1)
	case <-timeoutCh:
		err = errors.Errorf("timeout expired while starting chaincode %s for transaction", ccid)
		launchState.Notify(err)
		r.Metrics.LaunchTimeouts.With("chaincode", ccid).Add(1)
	}

	success := true
	if err != nil && !alreadyStarted {
		success = false
		chaincodeLogger.Debugf("stopping due to error while launching: %+v", err)
		defer r.Registry.Deregister(ccid)
	}

	r.Metrics.LaunchDuration.With(
		"chaincode", ccid,
		"success", strconv.FormatBool(success),
	).Observe(time.Since(startTime).Seconds())

	chaincodeLogger.Debug("launch complete")
	return err

View on GitHub (pinned to 2736b63f8f)

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)

Example fix

// before
chaincode:
  startuptimeout: 300s
// after
chaincode:
  startuptimeout: 600s

Defensive patterns

Strategy: retry

Validate before calling

// pre-check chaincode image/local binary is present and fast to start
exec.Command("docker", "image", "inspect", ccImage).Run() // must succeed

Try / catch

if err := launcher.Launch(ccid); err != nil && strings.Contains(err.Error(), "timeout expired while starting chaincode") {
    time.Sleep(5 * time.Second)
    // check chaincode logs, possibly increase startuptimeout, then retry
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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