What causes "Cluster repository persist error." in apache/shardingsphere?

Check ZooKeeper connectivity and health (zkCli.sh ls /, four-letter words like stat) from the ShardingSphere host; fix network/firewall/ensemble issues first.

apache/shardingsphere · error · ClusterRepositoryPersistException

HY000

HY000

Error message

Cluster repository persist error.

What it means

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.

Source

Thrown at mode/type/cluster/repository/provider/zookeeper/src/main/java/org/apache/shardingsphere/mode/repository/cluster/zookeeper/ZookeeperRepository.java:179

        try {
            client.setData().forPath(key, value.getBytes(StandardCharsets.UTF_8));
            // CHECKSTYLE:OFF
        } catch (final Exception ex) {
            // CHECKSTYLE:ON
            ZookeeperExceptionHandler.handleException(ex);
        }
    }
    
    @Override
    public String query(final String key) {
        try {
            return new String(client.getData().forPath(key), StandardCharsets.UTF_8);
        } catch (final KeeperException.NoNodeException ex) {
            return null;
            // CHECKSTYLE:OFF
        } catch (final Exception ex) {
            // CHECKSTYLE:ON
            throw new ClusterRepositoryPersistException(ex);
        }
    }
    
    @Override
    public boolean isExisted(final String key) {
        try {
            return null != client.checkExists().forPath(key);
            // CHECKSTYLE:OFF
        } catch (final Exception ex) {
            // CHECKSTYLE:ON
            ZookeeperExceptionHandler.handleException(ex);
            return false;
        }
    }
    
    @Override
    public void persistEphemeral(final String key, final String value) {
        try {

View on GitHub (pinned to e952770a21)

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.

Defensive patterns

Strategy: retry

Try / catch

try {
    repository.query(key);
} catch (final ClusterRepositoryPersistException ex) {
    Throwable cause = ex.getCause(); // ConnectionLoss / SessionExpired / NoAuth ...
    // classify cause; retry on transient connection loss after backoff, fix config on auth errors
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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).

Related errors

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