apache/rocketmq · error · AclException

NetAddress examine scope Exception netAddress is %s

Error message

NetAddress examine scope Exception netAddress is %s

What it means

AclUtils.IPv6AddressCheck validates the IPv6 address patterns allowed in plain_acl.yml (wildcard '*' and range '-') and throws when '*' appears anywhere but the last character. ACL rules may only end with a trailing wildcard like '2::ac5:78:*'; an embedded '*' such as '2::*:78' is rejected.

Source

Thrown at client/src/main/java/org/apache/rocketmq/acl/common/AclUtils.java:74

        if (b1 == null || b1.length == 0) return b2;
        if (b2 == null || b2.length == 0) return b1;
        byte[] total = new byte[b1.length + b2.length];
        System.arraycopy(b1, 0, total, 0, b1.length);
        System.arraycopy(b2, 0, total, b1.length, b2.length);
        return total;
    }

    public static String calSignature(byte[] data, String secretKey) {
        return AclSigner.calSignature(data, secretKey);
    }

    public static void IPv6AddressCheck(String netAddress) {
        if (isAsterisk(netAddress) || isMinus(netAddress)) {
            int asterisk = netAddress.indexOf("*");
            int minus = netAddress.indexOf("-");
            // '*' must be the end of netAddress if it exists
            if (asterisk > -1 && asterisk != netAddress.length() - 1) {
                throw new AclException(String.format("NetAddress examine scope Exception netAddress is %s", netAddress));
            }

            // format like "2::ac5:78:1-200:*" or "2::ac5:78:1-200" is legal
            if (minus > -1) {
                if (asterisk == -1) {
                    if (minus <= netAddress.lastIndexOf(":")) {
                        throw new AclException(String.format("NetAddress examine scope Exception netAddress is %s", netAddress));
                    }
                } else {
                    if (minus <= netAddress.lastIndexOf(":", netAddress.lastIndexOf(":") - 1)) {
                        throw new AclException(String.format("NetAddress examine scope Exception netAddress is %s", netAddress));
                    }
                }
            }
        }
    }

    public static String v6ipProcess(String netAddress) {

View on GitHub (pinned to 293f588571)

Solutions

1. Move the '*' to the very end of the address: '2::ac5:78:*' instead of '2::*:78'.
2. Use a range instead of a middle wildcard where possible: '2::ac5:78:1-200'.
3. After editing, validate the file by restarting the broker in foreground and watching for the AclException before it serves traffic.

Example fix

# before (plain_acl.yml)
whiteRemoteAddress: '2::*:78'

# after
whiteRemoteAddress: '2::ac5:78:*'

static boolean validIpv6AclPattern(String addr) {
    int a = addr.indexOf('*');
    if (a > -1 && a != addr.length() - 1) return false;
    // further rules: see errors 124/125 for '-' placement
    return true;
}

When it happens

Trigger: Broker startup or client ACL load where an account's IPv6 white/black host entry contains '*' that is not the final character (e.g. '2001::*:5') or a host like '*:1::1'.

Common situations: Hand-editing plain_acl.yml IPv6 entries by analogy with IPv4 (where '192.168.*.*' style habits carry over); copy-pasting IPv6 templates that put the wildcard in the middle.

Related errors

• The authorizationMetadataProvider is not configured.
• The actions is empty.
• The actions can not be Any.
• The source ip is empty.
• The source ip is invalid.

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/d6768798e853f6b7. Report an issue: GitHub.