hyperledger/fabric · error

identity is not well formed

Error message

identity is not well formed

What it means

The local MSP successfully deserialized the peer identity, but IsWellFormed on the local deserializer rejected it: the identity does not satisfy structural/organizational requirements (e.g., missing organizational units, disallowed cert properties). The raw MSP error is wrapped with this message. This check prevents identities that parse but are not acceptable for gossip security from being trusted.

Source

Thrown at internal/peer/gossip/mcs.go:308

	if err != nil {
		mcsLogger.Error("failed deserializing identity", err)
		return nil, nil, err
	}

	// Notice that peerIdentity is assumed to be the serialization of an identity.
	// So, first step is the identity deserialization and then verify it.

	// First check against the local MSP.
	// If the peerIdentity is in the same organization of this node then
	// the local MSP is required to take the final decision on the validity
	// of the signature.
	lDes := s.deserializer.GetLocalDeserializer()
	identity, err := lDes.DeserializeIdentity(peerIdentity)
	if err == nil {
		// No error means that the local MSP successfully deserialized the identity.
		// We now check additional properties.
		if err := lDes.IsWellFormed(sId); err != nil {
			return nil, nil, errors.Wrap(err, "identity is not well formed")
		}
		// TODO: The following check will be replaced by a check on the organizational units
		// when we allow the gossip network to have organization unit (MSP subdivisions)
		// scoped messages.
		// The following check is consistent with the SecurityAdvisor#OrgByPeerIdentity
		// implementation.
		// TODO: Notice that the following check saves us from the fact
		// that DeserializeIdentity does not yet enforce MSP-IDs consistency.
		// This check can be removed once DeserializeIdentity will be fixed.
		if identity.GetMSPIdentifier() == s.deserializer.GetLocalMSPIdentifier() {
			// Check identity validity

			// Notice that at this stage we don't have to check the identity
			// against any channel's policies.
			// This will be done by the caller function, if needed.
			return identity, nil, identity.Validate()
		}
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Read the wrapped cause under 'identity is not well formed' in peer logs for the exact MSP rejection reason.
2. Align OU/NodeOUs settings in config.yaml of the relevant MSPs across all peers.
3. Re-issue/re-enroll the offending peer's certificates so they match the MSP's requirements.
4. Refresh local MSP definitions from the channel config to pick up updated org MSP settings.
5. Ensure all peers run compatible Fabric versions with consistent identity validation rules.

Example fix

// before: trusting any deserializable identity
if _, _, err := cryptoService.getValidatedIdentity(peerIdentity); err != nil { ... }
// after: surface the well-formedness failure clearly for operators
if _, _, err := cryptoService.getValidatedIdentity(peerIdentity); err != nil {
    return fmt.Errorf("peer identity rejected by local MSP (check OUs/certs): %w", err)
}

// no caller-side check can fully predict MSP well-formedness; ensure identity is non-empty first
if len(peerIdentity) == 0 {
    return fmt.Errorf("empty identity")
}

if err := cryptoService.ValidateIdentity(peerIdentity); err != nil {
    if strings.Contains(err.Error(), "identity is not well formed") {
        log.Warnf("peer identity rejected by local MSP; check OU/NodeOUs config and cert issuance: %v", err)
        return errUntrustedPeer
    }
    return err
}

When it happens

Trigger: getValidatedIdentity path (ValidateIdentity/Verify/Expiration) with an identity whose properties fail lDes.IsWellFormed — wrong OU configuration, certificates not matching the local MSP's expectations, or identities from a peer MSP with mismatched configuration.

Common situations: MSP configuration drift after network re-organization (OU changes, NodeOUs enabled on one peer but not the other); certificates issued with SAN/OU fields the local MSP rejects; mixed Fabric versions where identity well-formedness rules differ; wrong crypto material deployed to a peer.

Related errors

• failed unmarshaling identity %s
• Could not serialize the signing identity: %s
• access denied: channel [%s] creator org unknown, creator is
• Failed deserializing proposal creator during channelless che
• failed unmarshalling peer's identity

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