error converting policy with reference '%s' on channel '%s'

Error message

error converting policy with reference '%s' on channel '%s' to SignaturePolicyEnvelope

What it means

After asserting the resolved policy implements policies.Converter, lifecycle calls cp.Convert() to produce a SignaturePolicyEnvelope. If that conversion fails — the policy cannot be materialized as a signature policy envelope, typically because referenced principals/MSPs cannot be resolved — this wrapped error is thrown. The underlying cause is embedded in the message.

Source

Thrown at core/chaincode/lifecycle/metadata_provider.go:98

	}

	switch policy := p.Type.(type) {
	case *peer.ApplicationPolicy_SignaturePolicy:
		return protoutil.MarshalOrPanic(policy.SignaturePolicy), nil
	case *peer.ApplicationPolicy_ChannelConfigPolicyReference:
		p, err := mp.ChannelPolicyReferenceProvider.NewPolicy(channelID, policy.ChannelConfigPolicyReference)
		if err != nil {
			return nil, errors.WithMessagef(err, "could not retrieve policy for reference '%s' on channel '%s'", policy.ChannelConfigPolicyReference, channelID)
		}

		cp, ok := p.(policies.Converter)
		if !ok {
			return nil, errors.Errorf("policy with reference '%s' on channel '%s' is not convertible to SignaturePolicyEnvelope", policy.ChannelConfigPolicyReference, channelID)
		}

		spe, err := cp.Convert()
		if err != nil {
			return nil, errors.WithMessagef(err, "error converting policy with reference '%s' on channel '%s' to SignaturePolicyEnvelope", policy.ChannelConfigPolicyReference, channelID)
		}

		return proto.Marshal(spe)
	default:
		// this will only happen if a new policy type is added to the oneof
		return nil, errors.Errorf("unsupported policy type %T on channel '%s'", policy, channelID)
	}
}

// Metadata implements the metadata retriever support interface for service discovery
func (mp *MetadataProvider) Metadata(channel string, ccName string, collections ...string) *chaincode.Metadata {
	ccInfo, err := mp.ChaincodeInfoProvider.ChaincodeInfo(channel, ccName)
	if err != nil {
		logger.Debugf("chaincode '%s' on channel '%s' not defined in _lifecycle. requesting metadata from lscc", ccName, channel)
		// fallback to legacy metadata via cclifecycle
		return mp.LegacyMetadataProvider.Metadata(channel, ccName, collections...)
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Read the wrapped cause in the error message and fix the underlying policy definition in channel config
Verify all MSPs referenced by the policy are configured on the peer (peer's msp config directory)
Refetch the latest channel config block after updates; ensure the peer is on the current config sequence
Redefine the endorsement policy as a simple explicit signature policy

Example fix

# before: policy references an org whose MSP is not deployed on the peer
# error converting policy with reference 'myPolicy' ...
# after: deploy the missing org MSP to the peer, then re-test discovery
peer channel fetch config config.block -c mychannel
configtxlator proto_decode --input config.block --type common.Config > config.json
# verify the referenced org exists, then restart peer with updated msp directory

Defensive patterns

Strategy: try-catch

Validate before calling

# Ensure all MSPs referenced by the policy exist on the peer
ls peer/msp/  # and compare against principals in the policy definition via configtxlator

Try / catch

envBytes, err := mp.toSignaturePolicyEnvelope(channelID, policyBytes)
if err != nil {
  if strings.Contains(err.Error(), "error converting policy with reference") {
    // inspect wrapped cause; likely MSP/config problem — fix channel config
  }
}

Prevention

Keep peer MSP configuration in sync with channel config principals
Apply config updates atomically across the network
Refetch config blocks after updates
Prefer simple signature policies over complex references

When it happens

Trigger: Metadata (service discovery) resolves a ChannelConfigPolicyReference to a converter policy whose Convert() returns an error, e.g. the policy references an MSP not configured on the peer or the channel config is stale/malformed.

Common situations: MSPs referenced by the policy missing from the peer's MSP config; partially applied channel config updates; config block fetched before an update completed; principals in the policy no longer exist after org changes.

Related errors

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