What causes "Unknown id on channelless checkACL %s" in hyperledger/fabric?

Unknown id on channelless checkACL %s

Error message

Unknown id on channelless checkACL %s

What it means

In CheckACLNoChannel, the identity argument must be *pb.SignedProposal, *common.Envelope, or []*protoutil.SignedData (plus *protoutil.SignedData handled earlier). Any other type reaches the default branch and returns this error, because no policy check path exists for that identity representation in the channelless flow.

Source

Thrown at core/aclmgmt/defaultaclprovider.go:179

	if policy == "" {
		aclLogger.Errorf("Unmapped channelless policy for %s", resName)
		return fmt.Errorf("Unmapped channelless policy for %s", resName)
	}

	switch typedData := idinfo.(type) {
	case *pb.SignedProposal:
		return d.policyChecker.CheckPolicyNoChannel(policy, typedData)
	case *common.Envelope:
		sd, err := protoutil.EnvelopeAsSignedData(typedData)
		if err != nil {
			return err
		}
		return d.policyChecker.CheckPolicyNoChannelBySignedData(policy, sd)
	case []*protoutil.SignedData:
		return d.policyChecker.CheckPolicyNoChannelBySignedData(policy, typedData)
	default:
		aclLogger.Errorf("Unmapped id on channelless checkACL %s", resName)
		return fmt.Errorf("Unknown id on channelless checkACL %s", resName)
	}
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Pass one of: *pb.SignedProposal, *common.Envelope, or []*protoutil.SignedData.
If you have a single *protoutil.SignedData, wrap it in a slice and use a path that accepts it, or construct an Envelope.
Extract SignedData from your request before invoking the ACL provider instead of passing the raw object.

Example fix

// before
aclProvider.CheckACLNoChannel(resName, signedData)
// after
aclProvider.CheckACLNoChannel(resName, []*protoutil.SignedData{signedData})

Defensive patterns

Strategy: type-guard

Validate before calling

switch v := idinfo.(type) {
case *pb.SignedProposal, *common.Envelope, []*protoutil.SignedData:
    // ok
default:
    return fmt.Errorf("CheckACLNoChannel requires SignedProposal, Envelope, or SignedData slice, got %T", v)
}

Type guard

func isChannellessCheckableID(v any) bool {
    switch v.(type) {
    case *pb.SignedProposal, *common.Envelope, []*protoutil.SignedData:
        return true
    }
    return false
}

Try / catch

if err := aclProvider.CheckACLNoChannel(resName, idinfo); err != nil {
    if strings.HasPrefix(err.Error(), "Unknown id on channelless") {
        return fmt.Errorf("unsupported identity type %T for ACL check", idinfo)
    }
    return err
}

Prevention

Wrap single *protoutil.SignedData into a slice before calling
Do not pass msp identities, unsigned Proposals, or request contexts as idinfo
Document accepted types in wrapper functions around the ACL provider

When it happens

Trigger: Calling CheckACLNoChannel with idinfo such as *protoutil.SignedData wrapped incorrectly, an msp identity object, a *pb.Proposal (unsigned), or any custom struct.

Common situations: Code copied from channel-based CheckACL passing types unsupported in the channelless path; generic middleware forwarding request contexts; using a single SignedData where the API expects the slice form via other helpers.

Related errors

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