What causes "failed to retrieve policy for reference %s" in hyperledger/fabric?

Check the exact policy reference string against policies defined in the channel config (configtxlator decode or `peer channel fetch config`)

hyperledger/fabric · error

failed to retrieve policy for reference %s

Error message

failed to retrieve policy for reference %s

What it means

ChannelPolicyReferenceProviderImpl.NewPolicy resolves a policy by name from the channel config policy manager. If the named policy reference does not exist in the channel configuration, it returns this error. It means an ApplicationPolicy with a ChannelConfigPolicyReference points at a policy name that is not defined on that channel.

Source

Thrown at core/policy/application.go:88

type ApplicationPolicyEvaluator struct {
	signaturePolicyProvider        SignaturePolicyProvider
	channelPolicyReferenceProvider ChannelPolicyReferenceProvider
}

// Manager defines functions to interface with the policy manager of a channel
type Manager interface {
	// GetPolicy returns a policy and true if it was the policy requested, or false if it is the default policy
	GetPolicy(id string) (policies.Policy, bool)
}

type ChannelPolicyReferenceProviderImpl struct {
	Manager
}

func (c *ChannelPolicyReferenceProviderImpl) NewPolicy(channelConfigPolicyReference string) (policies.Policy, error) {
	p, ok := c.GetPolicy(channelConfigPolicyReference)
	if !ok {
		return nil, errors.Errorf("failed to retrieve policy for reference %s", channelConfigPolicyReference)
	}

	return p, nil
}

// dynamicPolicyManager implements a policy manager that
// always acts on the latest config for this channel
type dynamicPolicyManager struct {
	channelPolicyManagerGetter policies.ChannelPolicyManagerGetter
	channelID                  string
}

func (d *dynamicPolicyManager) GetPolicy(id string) (policies.Policy, bool) {
	mgr := d.channelPolicyManagerGetter.Manager(d.channelID)
	if mgr == nil {
		// this will never happen - if we are here we
		// managed to retrieve the policy manager for
		// this channel once, and so by the way the

View on GitHub (pinned to 2736b63f8f)

Solutions

Check the exact policy reference string against policies defined in the channel config (configtxlator decode or `peer channel fetch config`)
Define the missing policy in configtx.yaml under the appropriate section (Application/Orderer policies) and update channel config
Verify the chaincode endorsement policy / ACL references a policy that exists in this specific channel
Fix path/case typos — policy references are path-like strings such as /Channel/Application/Readers

Example fix

// before
policy := &peer.ApplicationPolicy{Type: &peer.ApplicationPolicy_ChannelConfigPolicyReference{
    ChannelConfigPolicyReference: "/Channel/Application/Writters"}}
// after (policy name that exists in channel config)
policy := &peer.ApplicationPolicy{Type: &peer.ApplicationPolicy_ChannelConfigPolicyReference{
    ChannelConfigPolicyReference: "/Channel/Application/Writers"}}

Defensive patterns

Strategy: validation

Validate before calling

func policyExists(getter policies.ChannelPolicyManagerGetter, channel, ref string) error {
    mgr := getter.Manager(channel)
    if mgr == nil { return fmt.Errorf("no policy manager for channel %s", channel) }
    if _, ok := mgr.GetPolicy(ref); !ok {
        return fmt.Errorf("policy %q not defined in channel %s config", ref, channel)
    }
    return nil
}

Type guard

func policyResolvable(mgr policies.Manager, ref string) bool {
    _, ok := mgr.GetPolicy(ref)
    return ok
}

Try / catch

pol, err := provider.NewPolicy(ref)
if err != nil {
    if strings.Contains(err.Error(), "failed to retrieve policy for reference") {
        // fetch and decode channel config, fix or define the policy, then retry
    }
    return err
}

Prevention

Keep policy reference strings (e.g., /Channel/Application/Writers) in constants, not ad-hoc literals
Cross-check ACL and endorsement policy references against the channel config on every config update
Decode channel config with configtxlator in CI to assert referenced policies exist
When removing a policy in a config update, first migrate all references

When it happens

Trigger: Evaluating an ApplicationPolicy whose ChannelConfigPolicyReference string (e.g. '/Channel/Application/MyPolicy') does not match any policy defined in the channel's configtx; GetPolicy returns ok=false.

Common situations: Typo in the policy reference path, policy defined in one channel but endorsement/ACL on another channel references it, policy removed in a config update while still referenced by chaincode endorsement policy or ACLs.

Related errors

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