apache/shardingsphere · error · ClusterRepositoryPersistException

HY000

HY000

Error message

Cluster repository persist error.

What it means

ZookeeperExceptionHandler.handleException is the single funnel for ZooKeeper/Curator failures in write-path operations (isExisted, persist, etc.). NoNodeException and NodeExistsException (including as immediate cause) are logged at debug and ignored; InterruptedException re-sets the interrupt flag and logs without throwing; every other exception is logged at error ('Zookeeper exception occured.') and rethrown as ClusterRepositoryPersistException.

Source

Thrown at mode/type/cluster/repository/provider/zookeeper/src/main/java/org/apache/shardingsphere/mode/repository/cluster/zookeeper/exception/ZookeeperExceptionHandler.java:54

     *
     * <p>Ignore interrupt and node status exception.</p>
     *
     * @param cause to be handled exception
     * @throws ClusterRepositoryPersistException cluster persist repository exception
     */
    public static void handleException(final Exception cause) {
        if (null == cause) {
            log.info("cause is null");
            return;
        }
        if (isIgnoredException(cause) || null != cause.getCause() && isIgnoredException(cause.getCause())) {
            log.debug("Ignored exception for: {}", cause.getMessage());
        } else if (cause instanceof InterruptedException) {
            log.info("InterruptedException caught");
            Thread.currentThread().interrupt();
        } else {
            log.error("Zookeeper exception occured.", cause);
            throw new ClusterRepositoryPersistException(cause);
        }
    }
    
    private static boolean isIgnoredException(final Throwable cause) {
        return cause instanceof NoNodeException || cause instanceof NodeExistsException;
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Inspect the logged cause under 'Zookeeper exception occured.' — it distinguishes connectivity, auth, and timeout failures; fix that root cause first (ensemble health, network, server.yaml credentials).
2. For transient ConnectionLoss/SessionExpired during rolling restarts, bring the ZK majority back and let ShardingSphere reconnect; restart the ShardingSphere process if its Curator client will not recover.
3. Keep NoNode/NodeExists races out of your logic — they are already ignored here; guard other error handling on ClusterRepositoryPersistException and inspect its cause rather than the generic message.

try {
    repository.persist(key, value);
} catch (final ClusterRepositoryPersistException ex) {
    // handler already logged 'Zookeeper exception occured.' with the cause;
    // classify the cause: connectivity -> restore ensemble; auth -> fix ACL/digest; then retry
}

When it happens

Trigger: Any Curator call routed through this handler failing with a non-ignored exception: ConnectionLossException during a persist, SessionExpiredException, NoAuthException on ACL-protected nodes, OperationTimeoutException, or malformed path errors.

Common situations: Ensemble outages or rolling restarts while ShardingSphere writes metadata, session expiry after long GC or network partitions, wrong digest/ACL configuration, and racing watchers that hit nodes in transitional states other than the two ignored ones.

Related errors

• HY000
• HY000

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/e68d08b55554da25. Report an issue: GitHub.