hyperledger/fabric · error

could not launch chaincode %s

Error message

could not launch chaincode %s

What it means

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.

Source

Thrown at core/chaincode/chaincode_support.go:91

	Runtime                Runtime
	TotalQueryLimit        int
	UserRunsCC             bool
	UseWriteBatch          bool
	MaxSizeWriteBatch      uint32
	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()

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify the chaincode is correctly installed and committed on the channel, and that the invoked chaincode name/version matches the committed definition.
2. 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).
3. Ensure the container runtime (docker daemon or k8s) is healthy and the chaincode image is present/pullable on the node.
4. Confirm chaincode-to-peer connectivity (peer.chaincode.address, TLS certs) so the launched container can register with the peer.

Example fix

// before: invoking chaincode name that doesn't match the committed definition
peer chaincode invoke -n wrongcc -c '{"Args":["init"]}'
// after: use the name from the committed definition
peer chaincode list --committed   # confirm actual name/label
peer chaincode invoke -n mycc -C mychannel -c '{"function":"init","Args":[]}'

// Before invoking, verify the chaincode is committed on the channel
peer chaincode list --committed -C mychannel | grep mycc
// and that the container runtime is healthy
docker info > /dev/null && echo "docker ok"

func IsLaunchFailure(err error) bool {
	return err != nil && strings.Contains(err.Error(), "could not launch chaincode")
}

err := contract.SubmitTransaction("createAsset", "a1")
if err != nil {
    if IsLaunchFailure(err) {
        // check committed definitions and container runtime, then retry after remediation
        return fmt.Errorf("chaincode %s not launchable: %w", "mycc", err)
    }
    return err
}

When it happens

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

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

Related errors

• First message needs to be a register
• TLS is active but chaincode %s didn't send certificate
• Chaincode %s with given certificate hash %v not found in reg
• Chaincode %s with given certificate hash %v belongs to a dif
• Recv() error: %v, closing connection

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