hyperledger/fabric · error

could not unmarshal MSPIdentityAnonymity from principal

Error message

could not unmarshal MSPIdentityAnonymity from principal

What it means

For an ANONYMITY-classified principal, satisfiesPrincipalInternalV13 expects principal.Principal bytes to unmarshal as an MSPIdentityAnonymity proto message. When proto.Unmarshal fails, the principal payload is not a valid encoded MSPIdentityAnonymity and the MSP cannot determine the requested anonymity type, so it wraps and returns the unmarshal error.

Source

Thrown at msp/mspimpl.go:595

		return errors.New("The identities do not match")
	default:
		return errors.Errorf("invalid principal type %d", int32(principal.PrincipalClassification))
	}
}

// satisfiesPrincipalInternalV13 takes as arguments the identity and the principal.
// The function returns an error if one occurred.
// The function implements the additional behavior expected of an MSP starting from v1.3.
// For pre-v1.3 functionality, the function calls the satisfiesPrincipalInternalPreV13.
func (msp *bccspmsp) satisfiesPrincipalInternalV13(id Identity, principal *m.MSPPrincipal) error {
	switch principal.PrincipalClassification {
	case m.MSPPrincipal_COMBINED:
		return errors.New("SatisfiesPrincipalInternal shall not be called with a CombinedPrincipal")
	case m.MSPPrincipal_ANONYMITY:
		anon := &m.MSPIdentityAnonymity{}
		err := proto.Unmarshal(principal.Principal, anon)
		if err != nil {
			return errors.Wrap(err, "could not unmarshal MSPIdentityAnonymity from principal")
		}
		switch anon.AnonymityType {
		case m.MSPIdentityAnonymity_ANONYMOUS:
			return errors.New("Principal is anonymous, but X.509 MSP does not support anonymous identities")
		case m.MSPIdentityAnonymity_NOMINAL:
			return nil
		default:
			return errors.Errorf("Unknown principal anonymity type: %d", anon.AnonymityType)
		}

	default:
		// Use the pre-v1.3 function to check other principal types
		return msp.satisfiesPrincipalInternalPreV13(id, principal)
	}
}

// satisfiesPrincipalInternalV142 takes as arguments the identity and the principal.
// The function returns an error if one occurred.

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Construct the principal with a properly marshaled MSPIdentityAnonymity: proto.Marshal(&m.MSPIdentityAnonymity{AnonymityType: m.MSPIdentityAnonymity_NOMINAL}).
2. Verify the Principal bytes for ANONYMITY principals are not empty/nil before installing the policy.
3. If copying policies between environments, re-encode base64 payloads and confirm they decode to a valid MSPIdentityAnonymity message.

Example fix

// before
principal := &m.MSPPrincipal{PrincipalClassification: m.MSPPrincipal_ANONYMITY, Principal: []byte("nominal")}
// after
anon, _ := proto.Marshal(&m.MSPIdentityAnonymity{AnonymityType: m.MSPIdentityAnonymity_NOMINAL})
principal := &m.MSPPrincipal{PrincipalClassification: m.MSPPrincipal_ANONYMITY, Principal: anon}

if principal.PrincipalClassification == m.MSPPrincipal_ANONYMITY {
	anon := &m.MSPIdentityAnonymity{}
	if err := proto.Unmarshal(principal.Principal, anon); err != nil {
		return fmt.Errorf("malformed anonymity principal: %w", err)
	}
}

func isWellFormedAnonymityPrincipal(p *m.MSPPrincipal) bool {
	if p == nil || p.PrincipalClassification != m.MSPPrincipal_ANONYMITY || len(p.Principal) == 0 {
		return false
	}
	return proto.Unmarshal(p.Principal, &m.MSPIdentityAnonymity{}) == nil
}

When it happens

Trigger: Passing an MSPPrincipal with PrincipalClassification=ANONYMITY whose Principal bytes are empty, nil, malformed, or actually an encoded string/role rather than a marshaled m.MSPIdentityAnonymity.

Common situations: Building the principal by putting a raw string or role spec into Principal while setting the ANONYMITY classification; a policy file edited by hand truncating the base64 payload; proto version mismatch producing incompatible encoded bytes.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• could not unmarshal CombinedPrincipal from principal
• could not unmarshal OrganizationUnit from principal
• Principal is anonymous, but X.509 MSP does not support anony
• Unknown principal anonymity type: %d
• error unmarshalling SerializedIdentity

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