apache/shardingsphere · error · SQLWrapperException

HY000

HY000

Error message

Underlying SQL state: %s, underlying error code: %s.

What it means

Thrown by DatabaseRuleItemManager.alter when refreshing the in-memory database after a rule item change (processor.swapRuleItemConfiguration + changeRuleItemConfiguration followed by databaseRuleConfigManager.refresh) raises a SQLException. The SQLWrapperException preserves the underlying SQLState and vendor error code (reported as HY000 at the generic layer); the original SQLException is the cause.

Source

Thrown at mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/manager/rule/DatabaseRuleItemManager.java:65

     * Alter rule item.
     *
     * @param databaseRuleNodePath database rule node path
     * @throws SQLWrapperException SQL wrapper exception
     */
    @SuppressWarnings({"rawtypes", "unchecked"})
    public void alter(final DatabaseRuleNodePath databaseRuleNodePath) {
        RuleItemConfigurationChangedProcessor processor = TypedSPILoader.getService(RuleItemConfigurationChangedProcessor.class,
                new RuleChangedItemType(databaseRuleNodePath.getRuleType(), databaseRuleNodePath.getDatabaseRuleItem().getType()));
        String yamlContent = metaDataPersistFacade.getVersionService().loadContent(new VersionNodePath(databaseRuleNodePath));
        String databaseName = databaseRuleNodePath.getDatabase().getDatabaseName();
        RuleConfiguration currentRuleConfig = processor.findRuleConfiguration(metaDataContexts.getMetaData().getDatabase(databaseName));
        String itemName = databaseRuleNodePath.getDatabaseRuleItem().getName();
        synchronized (this) {
            processor.changeRuleItemConfiguration(itemName, currentRuleConfig, processor.swapRuleItemConfiguration(itemName, yamlContent));
            try {
                databaseRuleConfigManager.refresh(databaseName, currentRuleConfig);
            } catch (final SQLException ex) {
                throw new SQLWrapperException(ex);
            }
        }
    }
    
    /**
     * Drop rule item.
     *
     * @param databaseRuleNodePath database rule node path
     * @throws SQLWrapperException SQL wrapper exception
     */
    @SuppressWarnings({"rawtypes", "unchecked"})
    public void drop(final DatabaseRuleNodePath databaseRuleNodePath) {
        String databaseName = databaseRuleNodePath.getDatabase().getDatabaseName();
        Preconditions.checkState(metaDataContexts.getMetaData().containsDatabase(databaseName), "No database '%s' exists.", databaseName);
        RuleItemConfigurationChangedProcessor processor = TypedSPILoader.getService(RuleItemConfigurationChangedProcessor.class,
                new RuleChangedItemType(databaseRuleNodePath.getRuleType(), null == databaseRuleNodePath.getDatabaseRuleItem() ? null : databaseRuleNodePath.getDatabaseRuleItem().getType()));
        RuleConfiguration currentRuleConfig = processor.findRuleConfiguration(metaDataContexts.getMetaData().getDatabase(databaseName));
        String itemName = null == databaseRuleNodePath.getDatabaseRuleItem() ? null : databaseRuleNodePath.getDatabaseRuleItem().getName();

View on GitHub (pinned to e952770a21)

Solutions

1. Inspect the wrapped cause (SQLException) — its SQLState and vendor error code, named in this exception's message, identify the real failure; fix that (restore connectivity, correct the rule config, repair referenced objects).
2. Validate the new rule item configuration against the actual storage nodes before persisting it to the governance node.
3. Revert or correct the rule item change and let the node watcher re-run alter so metadata converges to a consistent state.

try {
    databaseRuleItemManager.alter(path);
} catch (final SQLWrapperException ex) {
    SQLException cause = (SQLException) ex.getCause();
    // log cause.getSQLState() + cause.getErrorCode(); fix the storage-side problem it names
}

When it happens

Trigger: A governance-node update to a single rule item (e.g. one sharding algorithm or encryptor entry) where re-refreshing the rule configuration executes SQL against storage nodes that fails — bad storage unit config, dropped backend table, connection failure during refresh, or invalid generated SQL from the new rule config.

Common situations: Altering a rule whose new configuration references a nonexistent storage unit or algorithm, a backend database that became unreachable between plan and apply, or a dialect incompatibility where refresh-time SQL (e.g. metadata reload) is invalid on the storage engine.

Related errors

• HY000
• database_gateway_execute_query only supports parser-approved
• database_gateway_execute_update does not accept read-only SQ
• Query did not return a result set.
• Statement class is not supported.

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