hyperledger/fabric · error

could not unmarshal signature policy envelope

Error message

could not unmarshal signature policy envelope

What it means

This error wraps a protobuf unmarshal failure while decoding bytes into a common.SignaturePolicyEnvelope in the v2.0 application-policy translator. It is thrown because the input bytes are not a valid serialized SignaturePolicyEnvelope, so the translator cannot produce a peer.ApplicationPolicy.

Source

Thrown at core/handlers/validation/builtin/v20/validation_logic.go:58

}

//go:generate mockery -dir . -name StateBasedValidator -case underscore -output mocks/

// toApplicationPolicyTranslator implements statebased.PolicyTranslator
// by translating SignaturePolicyEnvelope policies into ApplicationPolicy
// ones; this is required because the 2.0 validator is supplied with a
// policy evaluator that can only understand ApplicationPolicy policies.
type toApplicationPolicyTranslator struct{}

func (n *toApplicationPolicyTranslator) Translate(b []byte) ([]byte, error) {
	if len(b) == 0 {
		return b, nil
	}

	spe := &common.SignaturePolicyEnvelope{}
	err := proto.Unmarshal(b, spe)
	if err != nil {
		return nil, errors.Wrap(err, "could not unmarshal signature policy envelope")
	}

	return protoutil.MarshalOrPanic(&peer.ApplicationPolicy{
		Type: &peer.ApplicationPolicy_SignaturePolicy{
			SignaturePolicy: spe,
		},
	}), nil
}

// New creates a new instance of the default VSCC
// Typically this will only be invoked once per peer
func New(c vc.Capabilities, s vs.StateFetcher, d vi.IdentityDeserializer, pe vp.PolicyEvaluator, cor statebased.CollectionResources) *Validator {
	vpmgr := &statebased.KeyLevelValidationParameterManagerImpl{
		StateFetcher:     s,
		PolicyTranslator: &toApplicationPolicyTranslator{},
	}
	eval := statebased.NewV20Evaluator(vpmgr, pe, cor, s)
	sbv := statebased.NewKeyLevelValidator(eval, vpmgr)

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify the policy being translated is actually a SignaturePolicyEnvelope (check the config policy type in the channel configuration)
2. Regenerate the channel config/genesis block with a consistent fabric version (configtxlator can help inspect the policy)
3. Decode the bytes with configtxlator to confirm the policy structure and schema version
4. If writing tests (as TestToApplicationPolicyTranslator_Translate does), construct the envelope with protoutil/proto.Marshal of a valid &common.SignaturePolicyEnvelope

Example fix

// before
b := proto.Marshal(implicitMetaPolicy) // wrong type
pol, err := translator.Translate(b)
// after
spe := &common.SignaturePolicyEnvelope{Version: 0, Rule: cauthdsl.SignedBy(0), Identities: ids}
b := protoutil.MarshalOrPanic(spe)
pol, err := translator.Translate(b)

import "google.golang.org/protobuf/proto"
func isSignaturePolicyEnvelope(b []byte) bool {
    spe := &common.SignaturePolicyEnvelope{}
    return proto.Unmarshal(b, spe) == nil && spe.Identities != nil
}

func isSignaturePolicyEnvelope(b []byte) bool {
    spe := &common.SignaturePolicyEnvelope{}
    return proto.Unmarshal(b, spe) == nil
}

spe, err := translate(b)
if err != nil {
    if strings.Contains(err.Error(), "could not unmarshal signature policy envelope") {
        // log policy bytes, treat as invalid/unsupported policy config
    }
    return err
}

When it happens

Trigger: Translate() is called with bytes that are not a valid proto-encoded SignaturePolicyEnvelope — e.g. bytes produced by a different policy type (ImplicitMetaPolicy), corrupted policy bytes, or a policy marshaled by an incompatible proto schema.

Common situations: Channel config referencing an application policy whose stored value is an ImplicitMetaPolicy rather than a signature policy; fabric peers consuming configs generated by mismatched fabric versions; corrupted channel artifacts in genesis blocks or config update transactions.

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

• failed to unmarshal ApplicationPolicy bytes
• error unmarshalling
• error unmarshalling original config
• error unmarshalling updated config
• Error unmarshalling to SignaturePolicy: %s

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