peer will not accept external chaincode connection %s (excep

Error message

peer will not accept external chaincode connection %s (except in dev mode)

What it means

Returned by HandlerRegistry.Register when a chaincode attempts to connect to the peer but the peer never launched it (its chaincodeID is absent from r.launching) and unsolicited registrations are disallowed. The peer only accepts connections from chaincodes it launched itself, except in development mode.

Source

Thrown at core/chaincode/handler_registry.go:141

}

// Register adds a chaincode handler to the registry.
// An error will be returned if a handler is already registered for the
// chaincode. An error will also be returned if the chaincode has not already
// been "launched", and unsolicited registration is not allowed.
func (r *HandlerRegistry) Register(h *Handler) error {
	r.mutex.Lock()
	defer r.mutex.Unlock()

	if r.handlers[h.chaincodeID] != nil {
		chaincodeLogger.Debugf("duplicate registered handler(key:%s) return error", h.chaincodeID)
		return errors.Errorf("duplicate chaincodeID: %s", h.chaincodeID)
	}

	// This chaincode was not launched by the peer but is attempting
	// to register. Only allowed in development mode.
	if r.launching[h.chaincodeID] == nil && !r.allowUnsolicitedRegistration {
		return errors.Errorf("peer will not accept external chaincode connection %s (except in dev mode)", h.chaincodeID)
	}

	r.handlers[h.chaincodeID] = h

	chaincodeLogger.Debugf("registered handler complete for chaincode %s", h.chaincodeID)
	return nil
}

// Deregister clears references to state associated specified chaincode.
// As part of the cleanup, it closes the handler so it can cleanup any state.
// If the registry does not contain the provided handler, an error is returned.
func (r *HandlerRegistry) Deregister(ccid string) error {
	chaincodeLogger.Debugf("deregister handler: %s", ccid)

	r.mutex.Lock()
	handler := r.handlers[ccid]
	delete(r.handlers, ccid)
	delete(r.launching, ccid)

View on GitHub (pinned to 2736b63f8f)

Solutions

Enable dev mode on the peer (CORE_PEER_CHAINCODE_DEV_MODE=true or --peer-chaincodedev) when running chaincode externally.
Let the peer launch the chaincode (peer chaincode invoke/install path) instead of starting it manually.
Ensure CORE_CHAINCODE_ID_NAME exactly matches the launched chaincode name:version.
If the peer restarted, restart the chaincode after the peer so the peer launches it and records the launching entry.

Example fix

// before: external chaincode vs production peer
CORE_CHAINCODE_ID_NAME=mycc:1.0 ./chaincode
// after (dev mode)
CORE_PEER_CHAINCODE_DEV_MODE=true peer node start
CORE_CHAINCODE_ID_NAME=mycc:1.0 ./chaincode

Defensive patterns

Strategy: validation

Validate before calling

// running chaincode externally requires dev mode
// verify first:
//   grep chaincodedev configtx / peer env: CORE_PEER_CHAINCODE_DEV_MODE=true
export CORE_CHAINCODE_ID_NAME=mycc:1.0
export CORE_PEER_TLS_ENABLED=false # typically also required in dev mode

Prevention

Only run chaincode manually against peers with dev mode enabled.
Let the peer launch chaincode in production (install/CCaaS lifecycle).
Match CORE_CHAINCODE_ID_NAME exactly to the deployed chaincode name:version.
Restart chaincode after peer restarts so the peer records the launching entry.

When it happens

Trigger: An externally started chaincode process (not launched via peer chaincode launch / CCaaS lifecycle) calls Register; r.launching[h.chaincodeID] is nil and r.allowUnsolicitedRegistration is false.

Common situations: Running chaincode manually on the host (CORE_CHAINCODE_ID_NAME set) against a production peer with dev mode off; peer restarted so 'launching' state was lost while the chaincode reconnected; mismatched CORE_CHAINCODE_ID_NAME vs. what the peer launched; building-mode/CCaaS misconfiguration.

Related errors

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