apache/rocketmq · error · AuthenticationException

create user to RocksDB failed

Error message

create user to RocksDB failed

What it means

Error "create user to RocksDB failed" thrown in apache/rocketmq.

Source

Thrown at auth/src/main/java/org/apache/rocketmq/auth/authentication/provider/LocalAuthenticationMetadataProvider.java:84

        this.userCache = Caffeine.newBuilder()
            .maximumSize(authConfig.getUserCacheMaxNum())
            .expireAfterAccess(authConfig.getUserCacheExpiredSecond(), TimeUnit.SECONDS)
            .refreshAfterWrite(authConfig.getUserCacheRefreshSecond(), TimeUnit.SECONDS)
            .executor(cacheRefreshExecutor)
            .build(new UserCacheLoader(this.storage));
    }

    @Override
    public CompletableFuture<Void> createUser(User user) {
        try {
            byte[] keyBytes = user.getUsername().getBytes(StandardCharsets.UTF_8);
            byte[] valueBytes = JSON.toJSONBytes(user);
            this.storage.put(AUTH_METADATA_COLUMN_FAMILY, keyBytes, keyBytes.length, valueBytes);
            this.storage.flushWAL();
            this.userCache.invalidate(user.getUsername());
        } catch (Exception e) {
            throw new AuthenticationException("create user to RocksDB failed", e);
        }
        return CompletableFuture.completedFuture(null);
    }

    @Override
    public CompletableFuture<Void> deleteUser(String username) {
        try {
            this.storage.delete(AUTH_METADATA_COLUMN_FAMILY, username.getBytes(StandardCharsets.UTF_8));
            this.storage.flushWAL();
            this.userCache.invalidate(username);
        } catch (Exception e) {
            throw new AuthenticationException("delete user from RocksDB failed", e);
        }
        return CompletableFuture.completedFuture(null);
    }

    @Override
    public CompletableFuture<Void> updateUser(User user) {

View on GitHub (pinned to 293f588571)

Solutions

1. Verify the RocksDB instance used for auth_user is opened and healthy before creating users; check broker logs for RocksDB lock or corruption errors.
2. Ensure the data directory for authentication metadata is writable and not occupied by another broker process.
3. Retry the createUser operation after fixing the underlying RocksDB failure; if corruption persists, restore or rebuild the metadata store.

When it happens

Trigger: Occurs when creating a user in the local RocksDB-backed authentication metadata store fails, typically due to RocksDB being locked/corrupted, disk I/O errors, or insufficient permissions on the data directory.

Common situations: RocksDB directory locked by another broker process; disk full or I/O error; corrupted RocksDB files; missing write permissions on the configured store path.

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