{"record":{"id":"24bf8b7490c782a1","repo":"apache/shenyu","slug":"sdk-compatibility-error-mcp-sdk-reflection-fields-are-not","errorCode":null,"errorMessage":"SDK COMPATIBILITY ERROR: MCP SDK reflection fields are not available. The MCP SDK version may be incompatible with this implementation. Tested SDK version: ${SUPPORTED_SDK_VERSION}. Please verify SDK version compatibility or check logs for field resolution errors.","messagePattern":"SDK COMPATIBILITY ERROR: MCP SDK reflection fields are not available\\. The MCP SDK version may be incompatible with this implementation\\. Tested SDK version: (.+?)\\. Please verify SDK version compatibility or check logs for field resolution errors\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"shenyu-plugin/shenyu-plugin-mcp-server/src/main/java/org/apache/shenyu/plugin/mcp/server/session/McpSessionHelper.java","lineNumber":207,"sourceCode":"        }\n    }\n\n    /**\n     * Checks if reflection fields are available and throws an informative exception if not.\n     *\n     * @throws IllegalStateException if reflection fields are not available\n     */\n    private static void checkReflectionAvailability() {\n        if (!fieldsResolved || Objects.isNull(asyncExchangeFieldCache) || Objects.isNull(sessionFieldCache)) {\n            // Attempt to re-resolve fields in case of delayed class loading\n            synchronized (FIELD_RESOLVE_LOCK) {\n                if (!fieldsResolved) {\n                    resolveReflectionFields();\n                }\n            }\n\n            if (!fieldsResolved || Objects.isNull(asyncExchangeFieldCache) || Objects.isNull(sessionFieldCache)) {\n                throw new IllegalStateException(\n                        \"SDK COMPATIBILITY ERROR: MCP SDK reflection fields are not available. \"\n                        + \"The MCP SDK version may be incompatible with this implementation. \"\n                        + \"Tested SDK version: \" + SUPPORTED_SDK_VERSION + \". \"\n                        + \"Please verify SDK version compatibility or check logs for field resolution errors.\");\n            }\n        }\n    }\n\n    /**\n     * Checks if the SDK reflection fields are available for use.\n     * This can be used for proactive compatibility checking.\n     *\n     * @return true if reflection fields are resolved and available\n     */\n    public static boolean isReflectionAvailable() {\n        return fieldsResolved && Objects.nonNull(asyncExchangeFieldCache) && Objects.nonNull(sessionFieldCache);\n    }\n","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-plugin/shenyu-plugin-mcp-server/src/main/java/org/apache/shenyu/plugin/mcp/server/session/McpSessionHelper.java#L189-L225","documentation":"IllegalStateException from McpSessionHelper.checkReflectionAvailability when the static reflection fields (McpSyncServerExchange.exchange, McpAsyncServerExchange.session) are not resolved even after a retry. These fields are resolved in a static initializer for MCP SDK 0.17.0; if NoSuchFieldException/SecurityException occurred (SDK API change or reflection blocked), all session lookups fail fast with this error.","triggerScenarios":"getSession -> checkReflectionAvailability finds fieldsResolved=false or null field caches, a re-resolve attempt also fails, and the error is thrown before any field access.","commonSituations":"Dependency upgrade pulling an MCP SDK where the internal fields were renamed/removed; running with a security manager blocking setAccessible at class-init time; native-image or restricted classloader environments where reflection resolution fails — the root cause is logged at startup as 'SDK COMPATIBILITY ERROR: Failed to resolve reflection fields'.","solutions":["Check startup logs for 'SDK COMPATIBILITY ERROR: Failed to resolve reflection fields' and the missing field name to identify the exact incompatibility","Pin io.modelcontextprotocol:mcp to 0.17.0 and Spring AI to 1.1.2, then rebuild the gateway module","Remove security-manager restrictions or add --add-opens/--add-exports for the MCP SDK packages on JDK 16+","Upgrade to a ShenYu version whose McpSessionHelper supports your SDK version, or adapt the field names in McpSessionHelper.resolveReflectionFields"],"exampleFix":"// before (pom.xml)\n<mcp.sdk.version>1.0.0</mcp.sdk.version>\n// after\n<mcp.sdk.version>0.17.0</mcp.sdk.version>","handlingStrategy":"validation","validationCode":"if (!McpSessionHelper.isReflectionAvailable()) {\n    // refuse to start or route MCP traffic\n    throw new IllegalStateException(\"MCP SDK reflection fields unresolved; incompatible SDK version\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    McpSessionHelper.getSessionId(exchange);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"SDK COMPATIBILITY ERROR\")) {\n        LOG.error(\"MCP SDK incompatible; tested: \" + McpSessionHelper.getSupportedSdkVersion()\n            + \"; check startup field-resolution logs\", e);\n    } else throw e;\n}","preventionTips":["Call McpSessionHelper.isReflectionAvailable() in a startup health check and fail deployment fast on false","Pin io.modelcontextprotocol:mcp 0.17.0 and Spring AI 1.1.2 in dependencyManagement","Verify startup logs show 'MCP SDK reflection fields resolved successfully' before routing MCP traffic"],"tags":["mcp","reflection","sdk-compatibility","startup"],"backgroundTag":"incompatible-source-type","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}