What causes "Unmapped policy for %s" in hyperledger/fabric?

Use the exact resource constants from aclmgmt/resources (e.g._acl Resources area) rather than hand-typed strings.

Unmapped policy for %s

Error message

Unmapped policy for %s

What it means

defaultACLProviderImpl.CheckACL maps a resource name to its default policy via cResourcePolicyMap (or the policy passed for resource-level). If no policy is registered for that channel resource, ACL evaluation cannot proceed and this error is returned. It means the resource name is not in Fabric's known default ACL resource list.

Source

Thrown at core/aclmgmt/defaultaclprovider.go:134

	return d
}

func (d *defaultACLProviderImpl) IsPtypePolicy(resName string) bool {
	_, ok := d.pResourcePolicyMap[resName]
	return ok
}

// CheckACL provides default (v 1.0) behavior by mapping resources to their ACL for a channel.
func (d *defaultACLProviderImpl) CheckACL(resName string, channelID string, idinfo any) error {
	// the default behavior is to use p type if defined and use channeless policy checks
	policy := d.pResourcePolicyMap[resName]
	if policy != "" {
		channelID = ""
	} else {
		policy = d.cResourcePolicyMap[resName]
		if policy == "" {
			aclLogger.Errorf("Unmapped policy for %s", resName)
			return fmt.Errorf("Unmapped policy for %s", resName)
		}
	}
	aclLogger.Debugw("Applying default access policy for resource", "channel", channelID, "policy", policy, "resource", resName)

	switch typedData := idinfo.(type) {
	case *pb.SignedProposal:
		return d.policyChecker.CheckPolicy(channelID, policy, typedData)
	case *common.Envelope:
		sd, err := protoutil.EnvelopeAsSignedData(typedData)
		if err != nil {
			return err
		}
		return d.policyChecker.CheckPolicyBySignedData(channelID, policy, sd)
	case *protoutil.SignedData:
		return d.policyChecker.CheckPolicyBySignedData(channelID, policy, []*protoutil.SignedData{typedData})
	case []*protoutil.SignedData:
		return d.policyChecker.CheckPolicyBySignedData(channelID, policy, typedData)
	default:

View on GitHub (pinned to 2736b63f8f)

Solutions

Use the exact resource constants from aclmgmt/resources (e.g._acl Resources area) rather than hand-typed strings.
Verify the resource exists in your Fabric version's defaultaclprovider cResourcePolicyMap.
If it's a config-driven ACL, add the resource mapping in channel config ACLs section.
Check the log line 'Unmapped policy for <res>' to see the offending name and fix it.

Defensive patterns

Strategy: validation

Validate before calling

var knownResources = map[string]bool{
    aclmgmt.Resources_Lifecycle_ChaincodeExists: true,
    aclmgmt.Resources_Lifecycle_GetInstalledChaincode: true,
    // ... populate from aclmgmt/resources for your version
}
if !knownResources[resName] {
    return fmt.Errorf("resource %q has no default ACL mapping", resName)
}

Try / catch

if err := aclProvider.CheckACL(resName, channelID, signedProp); err != nil {
    if strings.HasPrefix(err.Error(), "Unmapped policy") {
        log.Fatalf("resource %q unknown to this peer version", resName)
    }
    return err
}

Prevention

Reference resource names from the aclmgmt/resources generated constants, never strings typed by hand
Pin client/peer code to the same Fabric release
Review channel config ACLs overrides so every custom resource has a mapping

When it happens

Trigger: Calling aclmgmt CheckACL(resName, channelID, idinfo) with a resource name absent from cResourcePolicyMap and no explicit policy override; typically from a custom chaincode/system handler using an invalid _lifecycle or lscc resource string.

Common situations: Typo in resource name (e.g. _lifecycle/DeployChaincode vs correct constant); Fabric version change where a resource was renamed/removed; custom code referencing resources only valid in newer releases.

Related errors

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