What causes "could not retrieve policy for reference '%s' on channel '%s'" in hyperledger/fabric?

Check the reference against the channel config (configtxlator or 'peer channel fetch config') and fix the name/path

could not retrieve policy for reference '%s' on channel '%s'

Error message

could not retrieve policy for reference '%s' on channel '%s'

What it means

channelPolicyReferenceProviderImpl.NewPolicy resolves a channel-config policy reference to a policies.Policy via the channel's PolicyManager. If no policy exists under that reference name on the channel config, the lookup fails and this error is thrown. It means the policy name used (e.g. as endorsement policy reference) is not defined in the channel configuration.

Source

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

}

// ChannelPolicyReferenceProvider is used to determine if a set of signature is valid and complies with a policy
type ChannelPolicyReferenceProvider interface {
	// NewPolicy creates a new policy based on the policy bytes
	NewPolicy(channelID, channelConfigPolicyReference string) (policies.Policy, error)
}

type channelPolicyReferenceProviderImpl struct {
	ChannelConfigSource
}

// NewPolicy implements the method of the same name of the ChannelPolicyReferenceProvider interface
func (c *channelPolicyReferenceProviderImpl) NewPolicy(channelID, channelConfigPolicyReference string) (policies.Policy, error) {
	cc := c.GetStableChannelConfig(channelID)
	pm := cc.PolicyManager()
	p, ok := pm.GetPolicy(channelConfigPolicyReference)
	if !ok {
		return nil, errors.Errorf("could not retrieve policy for reference '%s' on channel '%s'", channelConfigPolicyReference, channelID)
	}

	return p, nil
}

// NewMetadataProvider returns a new MetadataProvider instance
func NewMetadataProvider(cip ChaincodeInfoProvider, lmp LegacyMetadataProvider, ccs ChannelConfigSource) *MetadataProvider {
	return &MetadataProvider{
		ChaincodeInfoProvider:  cip,
		LegacyMetadataProvider: lmp,
		ChannelPolicyReferenceProvider: &channelPolicyReferenceProviderImpl{
			ChannelConfigSource: ccs,
		},
	}
}

type MetadataProvider struct {
	ChaincodeInfoProvider          ChaincodeInfoProvider

View on GitHub (pinned to 2736b63f8f)

Solutions

Check the reference against the channel config (configtxlator or 'peer channel fetch config') and fix the name/path
Use a policy that exists, e.g. /Channel/Application/Endorsement or majority endorsement via 'peer lifecycle chaincode approveformyorg -E'
Update the chaincode definition/approval to reference a valid policy after any config update that removed policies
Ensure you reference the policy on the correct channel

Example fix

// before: reference to nonexistent policy
peer lifecycle chaincode approveformyorg -C mychannel --name mycc -E /Channel/Application/MyTypoPolicy
// error
// after: use an existing channel policy
peer lifecycle chaincode approveformyorg -C mychannel --name mycc -E /Channel/Application/Endorsement

Defensive patterns

Strategy: validation

Validate before calling

# Before using a policy reference, confirm it exists in channel config
peer channel fetch config config.block -c mychannel
configtxlator proto_decode --input config.block --type common.Config > config.json
jq '.channel_group.groups.Application.policies | keys' config.json

Try / catch

p, err := provider.NewPolicy(channelID, ref)
if err != nil {
  if strings.Contains(err.Error(), "could not retrieve policy for reference") {
    // fall back to a default signature policy or fail fast with a clear message
  }
}

Prevention

List channel policies with configtxlator before referencing them
Use exact paths like /Channel/Application/Endorsement
Re-check references after any channel config update
Prefer explicit signature policies over channel references when unsure

When it happens

Trigger: Endorsement policy given as '/Channel/Application/SomePolicy' or 'channelconfig-policy-name' that does not exist in the channel config; MetadataProvider building discovery/commit metadata resolves the reference via pm.GetPolicy and gets ok=false.

Common situations: Typo in policy path (e.g. /Channel/Application/LifecycleEndorsement misspelled); policy defined at Organization level but referenced at Channel level; policy removed in a config update while chaincodes still reference it; referencing the policy on a different channel where it is not defined.

Related errors

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