alibaba/nacos · error · IllegalStateException

DatabaseDialect plugin is disabled: + databaseType + . Plea

Error message

DatabaseDialect plugin is disabled:  + databaseType + . Please enable it via plugin management API.

What it means

Thrown by DatabaseDialectManager.getDialect as IllegalStateException when PluginStateCheckerHolder reports the DATASOURCE_DIALECT plugin for the given databaseType is disabled. The dialect implementation may exist in SUPPORT_DIALECT_MAP but is gated by the plugin state checker, so it cannot be used until re-enabled.

Source

Thrown at plugin/datasource/src/main/java/com/alibaba/nacos/plugin/datasource/manager/DatabaseDialectManager.java:73

        
        for (DatabaseDialect dialect : dialectList) {
            String dialectType = dialect == null ? null : dialect.getType();
            PluginRegistryUtils.registerFirst(SUPPORT_DIALECT_MAP,
                PluginType.DATASOURCE_DIALECT.getType(), dialectType, dialect, LOGGER);
        }
        if (SUPPORT_DIALECT_MAP.isEmpty()) {
            LOGGER.warn(
                "[DatasourceDialectManager] Load DatabaseDialect fail, No DatabaseDialect implements");
        }
    }
    
    public DatabaseDialect getDialect(String databaseType) {
        // Check if plugin is enabled
        if (!PluginStateCheckerHolder.isPluginEnabled(PluginType.DATASOURCE_DIALECT.getType(),
            databaseType)) {
            LOGGER.debug("[DatabaseDialectManager] Plugin DATASOURCE_DIALECT:{} is disabled",
                databaseType);
            throw new IllegalStateException(
                "DatabaseDialect plugin is disabled: " + databaseType
                    + ". Please enable it via plugin management API.");
        }
        
        DatabaseDialect databaseDialect = SUPPORT_DIALECT_MAP.get(databaseType);
        if (databaseDialect == null) {
            throw new IllegalStateException(
                "No DatabaseDialect implementation found for selected type: " + databaseType
                    + ". Please ensure the selected datasource plugin is loaded.");
        }
        return databaseDialect;
    }
    
    /**
     * Get DatasourceDialectManager instance.
     *
     * @return DataSourceDialectProvider
     */

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Re-enable the DATASOURCE_DIALECT plugin for the databaseType via the plugin management API.
2. Verify the plugin state with the plugin management/status endpoint before issuing queries.
3. Ensure startup plugin-state configuration does not disable a dialect that the deployment actively uses.

Example fix

// before: dialect plugin disabled
manager.getDialect("mysql"); // -> IllegalStateException disabled

// after: re-enable via plugin management API
// POST /v3/admin/plugin/enable { type:"DATASOURCE_DIALECT", name:"mysql" }
manager.getDialect("mysql");

if (!PluginStateCheckerHolder.isPluginEnabled(
        PluginType.DATASOURCE_DIALECT.getType(), databaseType)) {
    // re-enable via plugin management API before proceeding
}

static boolean dialectEnabled(String type) {
    return PluginStateCheckerHolder.isPluginEnabled(
        PluginType.DATASOURCE_DIALECT.getType(), type);
}

try {
    return manager.getDialect(type);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("is disabled")) {
        // enable plugin then retry
    } else throw e;
}

When it happens

Trigger: Calling getDialect(databaseType) when the datasource-dialect plugin for that type has been disabled via the plugin management API. Reached by SQL building/pagination components that need dialect-specific SQL.

Common situations: An operator disabling a dialect plugin through the plugin management API and then issuing queries that require that dialect; plugin state not restored after maintenance; misconfigured plugin enablement after an upgrade.

Related errors

• No DatabaseDialect implementation found for selected type:
• AiResourceStorage plugin is disabled: + storageKey.getProvi
• PARAMETER_VALIDATE_ERROR
• 102
• 103

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/96765e45d6ef1ceb. Report an issue: GitHub.