apache/shardingsphere · error · MCPUnavailableException

Database `%s` is not configured.

Error message

Database `%s` is not configured.

What it means

Thrown by WorkflowProxyQueryService.openConnection when the requested database name has no entry in the transaction resource manager's runtime database map. It means the MCP session is not bound to any configured database by that name, so no connection can be opened; MCPUnavailableException is a configuration/availability error, not a query failure.

Source

Thrown at mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/workflow/WorkflowProxyQueryService.java:97

    }
    
    @Override
    public boolean isSameIdentifier(final String databaseName, final IdentifierScope identifierScope, final String identifier, final String existingIdentifier) {
        return WorkflowSQLUtils.isSameIdentifier(getDatabaseCapability(databaseName).getIdentifierContext(), identifierScope, identifier, existingIdentifier);
    }
    
    private MCPDatabaseQueryFailedException createQueryFailedException(final String databaseName, final SQLException cause) {
        Optional<MCPDatabaseCapability> databaseCapability = databaseCapabilityProvider.provide(databaseName);
        MCPJDBCErrorCategory category = databaseCapability.isPresent()
                ? MCPJDBCExceptionClassifier.classify(databaseCapability.get().getDatabaseType(), cause)
                : MCPJDBCExceptionClassifier.classify(cause);
        return new MCPDatabaseQueryFailedException(category, cause);
    }
    
    private Connection openConnection(final String databaseName) throws SQLException {
        RuntimeDatabaseConfiguration runtimeDatabaseConfig = sessionManager.getTransactionResourceManager().getRuntimeDatabases().get(databaseName);
        if (null == runtimeDatabaseConfig) {
            throw new MCPUnavailableException(String.format("Database `%s` is not configured.", databaseName));
        }
        return runtimeDatabaseConfig.openConnection(databaseName);
    }
    
    private MCPDatabaseCapability getDatabaseCapability(final String databaseName) {
        return databaseCapabilityProvider.provide(WorkflowSQLUtils.normalizeIdentifier(databaseName)).orElseThrow(DatabaseCapabilityNotFoundException::new);
    }
    
    private List<Map<String, Object>> extractRows(final ResultSet resultSet) throws SQLException {
        ResultSetMetaData resultSetMetaData = resultSet.getMetaData();
        List<Map<String, Object>> result = new LinkedList<>();
        while (resultSet.next()) {
            Map<String, Object> row = new LinkedHashMap<>(resultSetMetaData.getColumnCount(), 1F);
            for (int index = 1; index <= resultSetMetaData.getColumnCount(); index++) {
                row.put(resultSetMetaData.getColumnLabel(index).toLowerCase(Locale.ENGLISH), resultSet.getObject(index));
            }
            result.add(row);
        }

View on GitHub (pinned to e952770a21)

Solutions

1. List the configured databases on the connected instance (e.g. SHOW DATABASES / the instance's registration tool) and use the exact name.
2. Verify the MCP server points at the ShardingSphere instance (proxy/JDBC runtime) that actually has the database configured.
3. If the database was recently registered, re-establish or refresh the MCP session so runtime database metadata is reloaded, then retry.

Example fix

// before
toolArguments.put("database", "sales_db");
// after
toolArguments.put("database", "salesdb"); // exact name as registered on the instance

if (!sessionManager.getTransactionResourceManager().getRuntimeDatabases().containsKey(databaseName)) {
    // list configured databases and fail fast with a clear message before calling the tool
}

const dbConfigured = name => configuredDatabases.includes(name); // populate from a SHOW DATABASES equivalent

try {
    queryService.query(databaseName, sql);
} catch (final MCPUnavailableException ex) {
    // re-check database registration; surface 'Database `X` is not configured.' to the user
}

When it happens

Trigger: Calling a workflow query/apply tool with databaseName that is not a registered storage database in the current ShardingSphere instance — a typo, a logical database name that was never created, or a database configured in a different instance than the one the MCP server is attached to.

Common situations: Misspelled database name (case or underscore mismatch), querying a database that exists in another environment/proxy, a database created after the MCP session snapshot was taken, or connecting the MCP server to a fresh instance before storage units are registered.

Related errors

• %s execution_mode is required.
• %s execution_mode is required.
• %s execution_mode must be one of %s.
• approved_steps must contain only %s.
• WF-VAL-002

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