{"record":{"id":"9b97fd24e4290747","repo":"apache/shardingsphere","slug":"hy000-9b97fd","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/ZookeeperRepository.java","lineNumber":179,"sourceCode":"        try {\n            client.setData().forPath(key, value.getBytes(StandardCharsets.UTF_8));\n            // CHECKSTYLE:OFF\n        } catch (final Exception ex) {\n            // CHECKSTYLE:ON\n            ZookeeperExceptionHandler.handleException(ex);\n        }\n    }\n    \n    @Override\n    public String query(final String key) {\n        try {\n            return new String(client.getData().forPath(key), StandardCharsets.UTF_8);\n        } catch (final KeeperException.NoNodeException ex) {\n            return null;\n            // CHECKSTYLE:OFF\n        } catch (final Exception ex) {\n            // CHECKSTYLE:ON\n            throw new ClusterRepositoryPersistException(ex);\n        }\n    }\n    \n    @Override\n    public boolean isExisted(final String key) {\n        try {\n            return null != client.checkExists().forPath(key);\n            // CHECKSTYLE:OFF\n        } catch (final Exception ex) {\n            // CHECKSTYLE:ON\n            ZookeeperExceptionHandler.handleException(ex);\n            return false;\n        }\n    }\n    \n    @Override\n    public void persistEphemeral(final String key, final String value) {\n        try {","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/mode/type/cluster/repository/provider/zookeeper/src/main/java/org/apache/shardingsphere/mode/repository/cluster/zookeeper/ZookeeperRepository.java#L161-L197","documentation":"Thrown by ZookeeperRepository.query when Curator's getData().forPath(key) fails with anything other than KeeperException.NoNodeException (which maps to null). Curator's API declares checked Exception, so connection loss, session expiry, ACL violations, and timeouts are all funnelled into ClusterRepositoryPersistException — a generic 'Cluster repository persist error.' with the original exception as cause.","triggerScenarios":"Any ZooKeeper read while the ensemble is unreachable (ConnectionLossException), the session expired (SessionExpiredException), the client is still connecting (.curator returned but not started), or the node requires ACLs the client does not hold (NoAuthException).","commonSituations":"ZooKeeper ensemble down or network-partitioned during metadata reads, session timeouts after GC pauses on the ShardingSphere process, restarted ZK that lost ephemeral state, or migrated ZK with changed ACL/scheme (digest credentials in server.yaml wrong).","solutions":["Check ZooKeeper connectivity and health (zkCli.sh ls /, four-letter words like stat) from the ShardingSphere host; fix network/firewall/ensemble issues first.","Verify the governance center configuration (connection string, digest/auth) in server.yaml matches the ZooKeeper ensemble.","Tune Curator/ZK session and retry timeouts if transient instability (GC pauses, flaky links) causes session loss; restart the ShardingSphere node after fixing so a clean session is established."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    repository.query(key);\n} catch (final ClusterRepositoryPersistException ex) {\n    Throwable cause = ex.getCause(); // ConnectionLoss / SessionExpired / NoAuth ...\n    // classify cause; retry on transient connection loss after backoff, fix config on auth errors\n}","preventionTips":["Health-check the ZK ensemble before deploying governance changes","Keep server.yaml connection string and digest credentials in sync with the ensemble","Tune session/retry timeouts for GC-heavy ShardingSphere processes"],"tags":["zookeeper","cluster","governance","network"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}