This page organizes troubleshooting by user-visible symptoms for ShardingSphere-MCP, AI application integration, database connectivity, metadata inspection, queries, and rule changes. For feature-specific rule planning, execution, and validation issues, see the corresponding feature plugin documentation. When troubleshooting, distinguish external environment issues from MCP protection behavior. Database service availability, account privileges, gateway forwarding, and AI application configuration must be fixed in their own systems. MCP provides failure categories and runtime protection details to help locate the issue. If you have not completed the basic post-deployment checks yet, start with the health-check and observability entrypoints in Deployment before using this symptom-oriented page.
| Symptom | Possible cause | Action |
|---|---|---|
| MCP Server startup failure | Java version, config file path, distribution directory, or required YAML field is wrong. | Inspect the startup terminal and logs/mcp.log; use Java 21 or later, confirm that the config file exists, ensure that the distribution lib/ directory is complete, and configure at least one runtime database in runtimeDatabases. |
| The AI application cannot connect to ShardingSphere-MCP | Transport type, port, endpoint path, bind address, or the MCP Server configuration in the AI application is inconsistent. | Check transport.type, port, endpointPath, bindHost, and the address configured in the AI application. |
| Remote HTTP access fails or the HTTP request is rejected | HTTP bind address, Origin header, reverse proxy, gateway forwarding, or session attribution configuration does not satisfy the security policy. | Use loopback for local debugging; place remote access behind a controlled gateway or reverse proxy; check whether the gateway forwards the expected headers; inspect server logs for details. |
| No response in STDIO mode | STDIO is used as an interactive command-line entry, or the AI application does not launch the MCP process correctly. | Let the AI application launch ShardingSphere-MCP; inspect stderr or logs/mcp.log for diagnostics. |
| Databases or logical databases are not visible | The name in runtimeDatabases is wrong, connection failed, privileges are insufficient, or the target scope is empty. |
Read the currently visible databases; if a connection failure category is returned, follow the connection failure table below; confirm that the account can read metadata. |
| Tables, columns, or indexes cannot be found | The connection target is different, schema or namespace is wrong, account privileges are insufficient, or Proxy-visible logical metadata differs from the underlying physical database. | Confirm whether the target is ShardingSphere-Proxy or a direct database connection, then check schema, namespace, account privileges, and Proxy-visible metadata. |
| Query is rejected | The SQL is not read-only, or it contains locking reads, data changes, schema changes, privilege changes, or transaction control. | Use query statements for read-only tasks. For side-effecting tasks, preview the change first and then decide whether to execute it. |
| Query execution fails or the result is truncated | SQL syntax, target object, privilege, row limit, or timeout limit is wrong. | Inspect table structure first; narrow the predicate, reduce the projection, request fewer rows, or adjust timeout within the supported range. |
| Side-effecting SQL cannot be executed | The change SQL was not previewed and confirmed, or the current account lacks execution privileges. | Preview the change SQL, review the impact, and then confirm execution; privilege issues require administrator action. |
| Rule change planning or validation fails | The target is not ShardingSphere-Proxy, the target column is not visible, the algorithm is unavailable, required parameters are missing, the rule was not applied successfully, or a manual package has not been executed. | Ensure that runtimeDatabases points to a Proxy logical database; provide the rule target, algorithm, and parameters according to the feature plugin documentation; validate again after manual execution is completed. |
Additional notes:
username and driverClassName must be declared explicitly and cannot be empty; a no-password account can omit password or use "".runtimeDatabases is required at startup and must contain at least one runtime database.When a runtime database or ShardingSphere-Proxy connection fails, MCP responses return a connection failure category to help locate the issue. Categories describe the failure cause without exposing JDBC URLs, passwords, environment variables, or stack traces.
| Category | Meaning |
|---|---|
missing_jdbc_driver |
The configured JDBC driver cannot be found. |
authentication_failed |
Username or password authentication failed. |
authorization_failed |
The current account does not have permission to access the target database or metadata. |
connection_timeout |
The connection timed out. Check the address, port, network, or timeout settings. |
invalid_configuration |
Runtime database configuration is incomplete or inconsistent. |
database_unavailable |
The target database or ShardingSphere-Proxy is currently unavailable. |
connection_failed |
The connection failed, but cannot be classified into a more specific cause. |
database_not_visible |
The specified database or logical database is not visible to the current connection. |
| Protection | Meaning | Action |
|---|---|---|
| Query row limit | Queries return at most 100 rows by default, and one query can request at most 5000 rows. | When a result is truncated, narrow the predicate, reduce the projection, or request fewer rows. |
| Query timeout | One query can request at most 300000 milliseconds as the timeout. | After a timeout, narrow the query scope or adjust timeout within the supported range. |
| Tool-call quota | When the current MCP session reaches the tool-call protection limit, MCP returns tool_call_limit_exceeded. |
Close the current session and create a new MCP session. |
| Side-effect execution | Data, schema, rule, privilege, or transaction-state changes require preview and confirmation before execution. | Review the preview before deciding whether to execute. |
The following items are documented as known follow-up code improvements. Until the code changes are completed, users should rely on the current tool names, error categories, and runtime behavior.
| Improvement | Reason | Recommendation |
|---|---|---|
| Connectivity validation tool name | The current tool name database_gateway_validate_proxy_connectivity can imply that only Proxy is validated, but the tool actually validates a configured runtime database connection. |
Rename it to a more neutral name, such as database_gateway_validate_runtime_database or database_gateway_validate_connectivity, and update descriptors, tests, and documentation together. |
| Error categories in runtime status | The connection failure categories include database_not_visible, but the safe category list in the runtime status resource is not fully aligned. |
Add this category to the runtime status resource so troubleshooting categories and runtime status stay consistent. |
| HTTP security error categories | Origin header and session attribution failures are currently located mainly through HTTP status codes and logs. | Add stable, non-sensitive error categories such as origin_not_allowed and session_attribution_mismatch, so AI applications and administrators can troubleshoot by category. |
Empty runtimeDatabases startup policy |
The current launch configuration requires runtimeDatabases to be non-empty. A missing or empty value fails startup validation. |
If startup without runtime databases should be supported later, adjust YAML validation, runtime status, startup logs, and documentation together. If the non-empty requirement remains, keep startup failure behavior and continue directing users to fix the configuration. |
| Query failure error categories | Query failures can come from SQL syntax, invisible objects, insufficient privileges, interrupted connections, or timeout. Users currently need to combine the error response with logs to identify the cause. | Add stable, non-sensitive categories and actions for query execution failures, such as syntax error, object not visible, insufficient privileges, and execution timeout, without exposing raw connection details or stack traces. |
| Metadata visibility error categories | When databases, schemas, tables, columns, or indexes are not visible, users need to inspect configuration, privileges, and connection target manually. | Return finer-grained visibility categories from metadata read and search results, such as database not visible, schema not visible, object not visible, or insufficient privileges, with the next checks to perform. |
| Secret reference mechanism | Rule changes may require keys or credentials, which are currently passed through external protected channels. | If built-in support is required later, design a secret reference or resolver mechanism instead of exposing sensitive values through the MCP Server. |
When reporting an issue, provide:
logs/mcp.log.