{"record":{"id":"6b024a9729b04eb6","repo":"apache/rocketmq","slug":"create-acl-to-rocksdb-failed","errorCode":null,"errorMessage":"create Acl to RocksDB failed.","messagePattern":"create 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":89,"sourceCode":"        this.aclCache = Caffeine.newBuilder()\n            .maximumSize(authConfig.getAclCacheMaxNum())\n            .expireAfterAccess(authConfig.getAclCacheExpiredSecond(), TimeUnit.SECONDS)\n            .refreshAfterWrite(authConfig.getAclCacheRefreshSecond(), TimeUnit.SECONDS)\n            .executor(cacheRefreshExecutor)\n            .build(new AclCacheLoader(this.storage));\n    }\n\n    @Override\n    public CompletableFuture<Void> createAcl(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(\"create Acl to RocksDB failed.\", e);\n        }\n        return CompletableFuture.completedFuture(null);\n    }\n\n    @Override\n    public CompletableFuture<Void> deleteAcl(Subject subject) {\n        try {\n            byte[] keyBytes = subject.getSubjectKey().getBytes(StandardCharsets.UTF_8);\n            this.storage.delete(AUTH_METADATA_COLUMN_FAMILY, keyBytes);\n            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","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/auth/src/main/java/org/apache/rocketmq/auth/authorization/provider/LocalAuthorizationMetadataProvider.java#L71-L107","documentation":"LocalAuthorizationMetadataProvider.createAcl() wraps any exception thrown while serializing the Acl to JSON and writing it to the local RocksDB ACL store (put + flushWAL). The cause chain (AuthorizationException with cause) carries the real failure: RocksDB I/O error, disk full, serialization failure, or the store being shut down/corrupt.","triggerScenarios":"createAcl while the RocksDB storage is in a bad state: disk full, store directory on a failing disk, store already closed during broker shutdown, or the Acl object containing data that fastjson cannot serialize.","commonSituations":"Disk exhaustion on the broker's config volume; ACL writes racing broker shutdown; filesystem errors on the store path; a custom Subject/Acl subclass with non-serializable fields.","solutions":["Inspect the nested cause of the AuthorizationException to identify the real RocksDB or serialization error","Check disk space and filesystem health on the auth config path (df -h; dmesg | grep -i error)","If the store was closed during shutdown, retry the ACL creation after the broker is fully up","Verify the Acl/Subject objects only contain serializable fields before submission"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    provider.createAcl(acl).join();\n} catch (CompletionException e) {\n    Throwable real = ExceptionUtils.getRealException(e);\n    if (real instanceof AuthorizationException && real.getCause() != null) {\n        log.error(\"createAcl store failure: {}\", real.getCause().getMessage());\n    }\n}","preventionTips":["Monitor free space on the broker config volume so RocksDB writes never hit ENOSPC","Do not issue ACL mutations while the broker is shutting down","Back up the acls RocksDB directory before upgrades"],"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"}