{"record":{"id":"e68d08b55554da25","repo":"apache/shardingsphere","slug":"hy000-e68d08","errorCode":"HY000","errorMessage":"Cluster repository persist error.","messagePattern":"Cluster repository persist error\\.","errorType":"exception","errorClass":"ClusterRepositoryPersistException","httpStatus":null,"severity":"error","filePath":"mode/type/cluster/repository/provider/zookeeper/src/main/java/org/apache/shardingsphere/mode/repository/cluster/zookeeper/exception/ZookeeperExceptionHandler.java","lineNumber":54,"sourceCode":"     *\n     * <p>Ignore interrupt and node status exception.</p>\n     *\n     * @param cause to be handled exception\n     * @throws ClusterRepositoryPersistException cluster persist repository exception\n     */\n    public static void handleException(final Exception cause) {\n        if (null == cause) {\n            log.info(\"cause is null\");\n            return;\n        }\n        if (isIgnoredException(cause) || null != cause.getCause() && isIgnoredException(cause.getCause())) {\n            log.debug(\"Ignored exception for: {}\", cause.getMessage());\n        } else if (cause instanceof InterruptedException) {\n            log.info(\"InterruptedException caught\");\n            Thread.currentThread().interrupt();\n        } else {\n            log.error(\"Zookeeper exception occured.\", cause);\n            throw new ClusterRepositoryPersistException(cause);\n        }\n    }\n    \n    private static boolean isIgnoredException(final Throwable cause) {\n        return cause instanceof NoNodeException || cause instanceof NodeExistsException;\n    }\n}\n","sourceCodeStart":36,"sourceCodeEnd":62,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/mode/type/cluster/repository/provider/zookeeper/src/main/java/org/apache/shardingsphere/mode/repository/cluster/zookeeper/exception/ZookeeperExceptionHandler.java#L36-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    repository.persist(key, value);\n} catch (final ClusterRepositoryPersistException ex) {\n    // handler already logged 'Zookeeper exception occured.' with the cause;\n    // classify the cause: connectivity -> restore ensemble; auth -> fix ACL/digest; then retry\n}","preventionTips":["Remember NoNode/NodeExists are ignored by design — design watchers around that","Distinguish transient (connection loss, session expiry) from permanent (auth, bad path) causes before retrying","Centralize ZK error handling on ClusterRepositoryPersistException and inspect its cause, not the generic message"],"tags":["zookeeper","cluster","governance","error-handling"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}