claimed to start chaincode container for %s but could not fi

Error message

claimed to start chaincode container for %s but could not find handler

What it means

After ChaincodeSupport.Launch successfully launches a chaincode (cs.Launcher.Launch returned no error), it looks up the connection handler in the HandlerRegistry. If no handler is registered despite the launcher claiming it started the container, the peer raises this error. It signals an internal race/state inconsistency: the chaincode container was started but never completed registration with the peer before the lookup.

Source

Thrown at core/chaincode/chaincode_support.go:96

	UseGetMultipleKeys     bool
	MaxSizeGetMultipleKeys uint32
}

// Launch starts executing chaincode if it is not already running. This method
// blocks until the peer side handler gets into ready state or encounters a fatal
// error. If the chaincode is already running, it simply returns.
func (cs *ChaincodeSupport) Launch(ccid string) (*Handler, error) {
	if h := cs.HandlerRegistry.Handler(ccid); h != nil && h.State() == Ready {
		return h, nil
	}

	if err := cs.Launcher.Launch(ccid, cs); err != nil {
		return nil, errors.Wrapf(err, "could not launch chaincode %s", ccid)
	}

	h := cs.HandlerRegistry.Handler(ccid)
	if h == nil {
		return nil, errors.Errorf("claimed to start chaincode container for %s but could not find handler", ccid)
	}

	return h, nil
}

// LaunchInProc is a stopgap solution to be called by the inproccontroller to allow system chaincodes to register
func (cs *ChaincodeSupport) LaunchInProc(ccid string) <-chan struct{} {
	launchStatus, ok := cs.HandlerRegistry.Launching(ccid)
	if ok {
		chaincodeLogger.Panicf("attempted to launch a system chaincode which has already been launched")
	}

	return launchStatus.Done()
}

// HandleChaincodeStream implements ccintf.HandleChaincodeStream for all vms to call with appropriate stream
func (cs *ChaincodeSupport) HandleChaincodeStream(stream ccintf.ChaincodeStream) error {
	var deserializerFactory privdata.IdentityDeserializerFactoryFunc = func(channelID string) msp.IdentityDeserializer {

View on GitHub (pinned to 2736b63f8f)

Solutions

Check the chaincode container logs to see why it exited or failed to send REGISTER after starting.
Retry the transaction/invocation once node load subsides if the cause was slow startup racing the launch timeout.
Verify the chaincode image's entrypoint and connection config so it actually connects to the peer instead of exiting.
Increase launch/startup allowances in your environment (resources for the chaincode container) and check peer logs for handler registration timing.

Example fix

// before: chaincode container starts but resource limits kill it before registration
resources:
  limits:
    memory: "64Mi"
// after: raise limits so the chaincode lives long enough to register
resources:
  limits:
    memory: "512Mi"

Defensive patterns

Strategy: retry

Validate before calling

// Pre-warm the chaincode with a no-op invocation after deploy so registration completes
// before real traffic: invoke a harmless query like GetHistory or an empty init function.

Type guard

func IsHandlerMissingError(err error) bool {
	return err != nil && strings.Contains(err.Error(), "could not find handler")
}

Try / catch

for attempt := 0; attempt < 3; attempt++ {
    resp, err := contract.EvaluateTransaction("readAsset", "a1")
    if err != nil && IsHandlerMissingError(err) {
        time.Sleep(time.Duration(attempt+1) * 2 * time.Second) // backoff for slow registration
        continue
    }
    return resp, err
}

Prevention

Pre-warm chaincode after deployment before serving production traffic.
Give chaincode containers adequate CPU/memory so startup is fast.
Avoid hammering a just-deployed chaincode with concurrent invocations.
Monitor chaincode container exits; an image that starts and dies will always hit this.

When it happens

Trigger: Launcher.Launch returns without error but the chaincode handler isn't in HandlerRegistry yet or ever: the chaincode process started but crashed before sending REGISTER, a launch timeout window expired, or an in-process/system chaincode failed to register via the inproccontroller path.

Common situations: Slow chaincode startup exceeding the launch timeout under heavy node load; chaincode image that starts but exits immediately; system chaincode misconfigured so its in-process registration never happens; concurrent invocations racing launch of the same ccid.

Related errors

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