Chaincode %s with given certificate hash %v not found in reg

Error message

Chaincode %s with given certificate hash %v not found in registry

What it means

During registration the peer extracts the client certificate hash and looks it up in the registry mapper that stores chaincode-name-to-certificate mappings. If the certificate is valid but not registered (lookup returns empty), the peer rejects the register message with 'Chaincode %s with given certificate hash %v not found in registry'.

Source

Thrown at core/chaincode/accesscontrol/access.go:85

	err := proto.Unmarshal(msg.Payload, chaincodeID)
	if err != nil {
		logger.Warning("Failed unmarshalling message:", err)
		return err
	}
	ccName := chaincodeID.Name
	// Obtain certificate from stream
	hash := extractCertificateHashFromContext(stream.Context())
	if len(hash) == 0 {
		errMsg := fmt.Sprintf("TLS is active but chaincode %s didn't send certificate", ccName)
		logger.Warning(errMsg)
		return errors.New(errMsg)
	}
	// Look it up in the mapper
	registeredName := ac.mapper.lookup(certHash(hash))
	if registeredName == "" {
		errMsg := fmt.Sprintf("Chaincode %s with given certificate hash %v not found in registry", ccName, hash)
		logger.Warning(errMsg)
		return errors.New(errMsg)
	}
	if registeredName != ccName {
		errMsg := fmt.Sprintf("Chaincode %s with given certificate hash %v belongs to a different chaincode", ccName, hash)
		logger.Warning(errMsg)
		return errors.New(errMsg)
	}

	logger.Debug("Chaincode", ccName, "'s authentication is authorized")
	return nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Restart the chaincode and peer so the launch handler registers the certificate hash before the chaincode connects.
Ensure the chaincode uses the exact TLS certificate/key pair provisioned for its registered name (do not rotate certs without re-launching via the peer launch flow).
Avoid running duplicate chaincode containers with the same name but different certs; remove stale containers.
If in dev mode, use the peer chaincode launch path or re-register the connection instead of connecting ad hoc.

Example fix

// before: cert rotated but peer mapper still has old hash
# chaincode restarted with new tls.crt, peer unaware
// after: re-register via peer launch so the new cert hash is mapped
peer node restart # or delete stale chaincode container and let peer relaunch it

Defensive patterns

Strategy: retry

Validate before calling

// confirm the cert hash the chaincode will present matches the one provisioned at launch
cert, err := tls.LoadX509KeyPair(certPath, keyPath)
if err != nil { return err }
h := sha256.Sum256(cert.Certificate[0])
_ = h // compare against the hash registered in the peer's mapper

Type guard

func certMatchesRegistered(certDER []byte, registeredHash certHash) bool {
    h := sha256.Sum256(certDER)
    return certHash(h[:]) == registeredHash
}

Try / catch

if err := authenticator.authenticate(msg, stream); err != nil {
    if strings.Contains(err.Error(), "not found in registry") {
        // let the peer relaunch the chaincode to (re)register the cert, then reconnect
    }
}

Prevention

Launch chaincodes through the peer so cert hashes are registered before the first message
Do not rotate chaincode TLS certificates without restarting the peer/launch flow
Remove stale duplicate chaincode containers using the same name with different certs

When it happens

Trigger: A chaincode sends ChaincodeMessage_REGISTER over a TLS connection whose client cert hash is not in the Authenticator's mapper — i.e., the peer never pre-registered this connection (registerHandler was not called for this chaincode name/cert pair) or the cert differs from the registered one.

Common situations: Chaincode restarted with a new TLS certificate while the peer still holds the old mapping; launching a second instance of the same chaincode name with a different cert; peer reboot losing in-memory mappings while chaincode connections persist; dev-mode quirks where the handler registry was not populated.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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