{"record":{"id":"1cfc0a123650f8f3","repo":"apache/rocketmq","slug":"update-acl-to-rocksdb-failed","errorCode":null,"errorMessage":"update Acl to RocksDB failed.","messagePattern":"update Acl to RocksDB failed\\.","errorType":"exception","errorClass":"AuthorizationException","httpStatus":null,"severity":"error","filePath":"auth/src/main/java/org/apache/rocketmq/auth/authorization/provider/LocalAuthorizationMetadataProvider.java","lineNumber":117,"sourceCode":"            this.storage.flushWAL();\n            this.aclCache.invalidate(subject.getSubjectKey());\n        } catch (Exception e) {\n            throw new AuthorizationException(\"delete Acl from RocksDB failed.\", e);\n        }\n        return CompletableFuture.completedFuture(null);\n    }\n\n    @Override\n    public CompletableFuture<Void> updateAcl(Acl acl) {\n        try {\n            Subject subject = acl.getSubject();\n            byte[] keyBytes = subject.getSubjectKey().getBytes(StandardCharsets.UTF_8);\n            byte[] valueBytes = JSON.toJSONBytes(acl);\n            this.storage.put(AUTH_METADATA_COLUMN_FAMILY, keyBytes, keyBytes.length, valueBytes);\n            this.storage.flushWAL();\n            this.aclCache.invalidate(subject.getSubjectKey());\n        } catch (Exception e) {\n            throw new AuthorizationException(\"update Acl to RocksDB failed.\", e);\n        }\n        return CompletableFuture.completedFuture(null);\n    }\n\n    @Override\n    public CompletableFuture<Acl> getAcl(Subject subject) {\n        Acl acl = aclCache.get(subject.getSubjectKey());\n        if (acl == AclCacheLoader.EMPTY_ACL) {\n            return CompletableFuture.completedFuture(null);\n        }\n        return CompletableFuture.completedFuture(acl);\n    }\n\n    @Override\n    public CompletableFuture<List<Acl>> listAcl(String subjectFilter, String resourceFilter) {\n        List<Acl> result = new ArrayList<>();\n        CompletableFuture<List<Acl>> future = new CompletableFuture<>();\n        try {","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/auth/src/main/java/org/apache/rocketmq/auth/authorization/provider/LocalAuthorizationMetadataProvider.java#L99-L135","documentation":"LocalAuthorizationMetadataProvider.updateAcl() wraps exceptions from overwriting an existing Acl entry in the local RocksDB store (put + flushWAL + cache invalidation). The cause chain distinguishes RocksDB I/O errors from JSON serialization failures of the new Acl content.","triggerScenarios":"updateAcl with a store in a failed state, or an Acl whose policies contain objects fastjson cannot serialize; also triggered by disk-full during the WAL flush.","commonSituations":"Concurrent ACL updates while the broker is shutting down; full config disk; malformed policy objects (e.g. custom enum or circular references) breaking JSON.toJSONBytes.","solutions":["Examine the nested cause for the underlying RocksDB or JSON serialization error","Free disk space on the auth config volume if flushWAL is failing","Ensure the updated Acl contains only schema-valid PolicyEntry objects (actions, decision, resource set)","Retry once the broker storage is confirmed healthy (startup complete, no store errors in logs)"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    provider.updateAcl(acl).join();\n} catch (CompletionException e) {\n    Throwable real = ExceptionUtils.getRealException(e);\n    if (real.getCause() instanceof RocksDBException) { /* storage issue: check disk */ }\n}","preventionTips":["Validate the Acl object graph (serializable fields, valid policies) before update","Keep ACL mutations serialized through one admin path to avoid store contention during shutdown"],"tags":["auth","rocksdb","persistence","acl","rocketmq"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}