What causes "get Acl from RocksDB failed." in apache/rocketmq?

Check the nested cause: a JSON parse error points to a corrupt or version-incompatible stored value, an IllegalArgumentException from Subject.of points to a malformed key

apache/rocketmq · error · AuthorizationException

get Acl from RocksDB failed.

Error message

get Acl from RocksDB failed.

What it means

Thrown inside LocalAuthorizationMetadataProvider's AclCacheLoader.load() when reading an Acl back from RocksDB fails — either the raw get() throws, Subject.of(subjectKey) cannot parse the key, or JSON.parseObject cannot decode the stored value. Because this runs inside a Caffeine cache load, the AuthorizationException surfaces on whatever request triggered the cache miss (getAcl / authorization checks).

Source

Thrown at auth/src/main/java/org/apache/rocketmq/auth/authorization/provider/LocalAuthorizationMetadataProvider.java:203

        public AclCacheLoader(ConfigRocksDBStorage storage) {
            this.storage = storage;
        }

        @Override
        public Acl load(String subjectKey) {
            try {
                byte[] keyBytes = subjectKey.getBytes(StandardCharsets.UTF_8);
                Subject subject = Subject.of(subjectKey);

                byte[] valueBytes = this.storage.get(AUTH_METADATA_COLUMN_FAMILY, keyBytes);
                if (ArrayUtils.isEmpty(valueBytes)) {
                    return EMPTY_ACL;
                }
                Acl acl = JSON.parseObject(valueBytes, Acl.class);
                return Acl.of(subject, acl.getPolicies());
            } catch (Exception e) {
                throw new AuthorizationException("get Acl from RocksDB failed.", e);
            }
        }
    }
}

View on GitHub (pinned to 293f588571)

Solutions

Check the nested cause: a JSON parse error points to a corrupt or version-incompatible stored value, an IllegalArgumentException from Subject.of points to a malformed key
Delete and re-create the affected Acl entry to rewrite a clean value (deleteAcl + createAcl)
After upgrades, re-import ACLs if the stored schema is incompatible rather than mixing versions against one store
If many keys fail, consider rebuilding the acls RocksDB directory from an ACL export

Defensive patterns

Strategy: try-catch

Try / catch

try {
    Acl acl = provider.getAcl(subject).join();
} catch (CompletionException e) {
    Throwable real = ExceptionUtils.getRealException(e);
    if (real instanceof AuthorizationException && real.getCause() instanceof JSONException) {
        // corrupt/incompatible stored value: delete and re-create the Acl entry
    }
}

Prevention

Re-import (delete+create) ACLs after version upgrades instead of reusing old stores
Export ACLs to JSON backups so a corrupt store can be rebuilt quickly

When it happens

Trigger: A cache miss for a subject whose stored JSON is corrupt (partial write after crash), a stored value written by an incompatible older version whose Acl JSON layout no longer parses, or a subjectKey whose format does not round-trip through Subject.of().

Common situations: Upgrading RocketMQ across versions where the serialized Acl schema changed; RocksDB corruption after an unclean shutdown; a subject key with unexpected delimiters breaking Subject.of parsing.

Related errors

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