{"record":{"id":"84ab72c983989f0e","repo":"hyperledger/fabric","slug":"peer-will-not-accept-external-chaincode-connection","errorCode":null,"errorMessage":"peer will not accept external chaincode connection %s (except in dev mode)","messagePattern":"peer will not accept external chaincode connection (.+?) \\(except in dev mode\\)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/chaincode/handler_registry.go","lineNumber":141,"sourceCode":"}\n\n// Register adds a chaincode handler to the registry.\n// An error will be returned if a handler is already registered for the\n// chaincode. An error will also be returned if the chaincode has not already\n// been \"launched\", and unsolicited registration is not allowed.\nfunc (r *HandlerRegistry) Register(h *Handler) error {\n\tr.mutex.Lock()\n\tdefer r.mutex.Unlock()\n\n\tif r.handlers[h.chaincodeID] != nil {\n\t\tchaincodeLogger.Debugf(\"duplicate registered handler(key:%s) return error\", h.chaincodeID)\n\t\treturn errors.Errorf(\"duplicate chaincodeID: %s\", h.chaincodeID)\n\t}\n\n\t// This chaincode was not launched by the peer but is attempting\n\t// to register. Only allowed in development mode.\n\tif r.launching[h.chaincodeID] == nil && !r.allowUnsolicitedRegistration {\n\t\treturn errors.Errorf(\"peer will not accept external chaincode connection %s (except in dev mode)\", h.chaincodeID)\n\t}\n\n\tr.handlers[h.chaincodeID] = h\n\n\tchaincodeLogger.Debugf(\"registered handler complete for chaincode %s\", h.chaincodeID)\n\treturn nil\n}\n\n// Deregister clears references to state associated specified chaincode.\n// As part of the cleanup, it closes the handler so it can cleanup any state.\n// If the registry does not contain the provided handler, an error is returned.\nfunc (r *HandlerRegistry) Deregister(ccid string) error {\n\tchaincodeLogger.Debugf(\"deregister handler: %s\", ccid)\n\n\tr.mutex.Lock()\n\thandler := r.handlers[ccid]\n\tdelete(r.handlers, ccid)\n\tdelete(r.launching, ccid)","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/chaincode/handler_registry.go#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: external chaincode vs production peer\nCORE_CHAINCODE_ID_NAME=mycc:1.0 ./chaincode\n// after (dev mode)\nCORE_PEER_CHAINCODE_DEV_MODE=true peer node start\nCORE_CHAINCODE_ID_NAME=mycc:1.0 ./chaincode","handlingStrategy":"validation","validationCode":"// running chaincode externally requires dev mode\n// verify first:\n//   grep chaincodedev configtx / peer env: CORE_PEER_CHAINCODE_DEV_MODE=true\nexport CORE_CHAINCODE_ID_NAME=mycc:1.0\nexport CORE_PEER_TLS_ENABLED=false # typically also required in dev mode","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["hyperledger-fabric","chaincode","registration","dev-mode","security"],"backgroundTag":"unsolicited-chaincode-connection","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"}