apache/shenyu · error · RuntimeException

Import mcp server config failed:

Error message

Import mcp server config failed: 

What it means

importMcpConfig() wraps IOExceptions from the MCP config import into a RuntimeException with the prefix 'Import mcp server config failed: '. This happens when reading or fetching the swagger document for MCP tool registration fails at the IO level. IllegalArgumentException (validation) is re-thrown unwrapped for HTTP 400 handling.

Solutions

1. Check the cause chain for the IOException message (Connection refused, UnknownHost, timeout) and fix the network/URL issue.
2. Verify swaggerUrl points to a live, reachable endpoint from the admin server host.
3. Retry the import after network connectivity is restored — this error is often transient.
4. For planned unavailability, pre-validate reachability before invoking the import API.

InetAddress addr = InetAddress.getByName(URI.create(swaggerUrl).getHost());
if (!addr.isReachable(3000)) throw new IllegalStateException("swagger host unreachable before MCP import");

try {
    service.importMcpConfig(request);
} catch (IllegalArgumentException e) {
    return ResponseEntity.badRequest().body(e.getMessage());
} catch (RuntimeException e) {
    if (e.getCause() instanceof IOException) { scheduleRetry(request); } // transient network
    throw e;
}

When it happens

Trigger: Calling the MCP config import API (SwaggerImportServiceImpl.importMcpConfig) when fetchSwaggerDoc or body reading throws IOException: the swagger URL host is unreachable, connection reset, or reading the response body fails.

Common situations: Target backend service is down or misconfigured URL; DNS failure or firewall blocking the admin server; network timeouts when fetching a large swagger document; proxy misconfiguration in the admin environment.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Failed to get Swagger document, HTTP status code:
• Import failed:
• OpenAPI document is missing the top-level 'servers' field…
• Unsupported Swagger version, only Swagger 2.0 and OpenAPI…
• Invalid Swagger JSON format:

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/4de122c94201556f. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java:146

            validateSwaggerUrl(request.getSwaggerUrl());

            String swaggerJson = fetchSwaggerDoc(request.getSwaggerUrl());

            String namespaceId = StringUtils.defaultIfEmpty(request.getNamespaceId(), SYS_DEFAULT_NAMESPACE_ID);
            List<McpToolsRegisterDTO> mcpToolsRegisterDTOList = buildMcpToolRegisterDTO(swaggerJson, namespaceId);

            mcpToolsRegisterDTOList.forEach(mcpToolsRegisterDTO -> {
                shenyuClientRegisterMcpService.registerMcpTools(mcpToolsRegisterDTO);
            });

            return "Import mcp server config successful, supports Swagger 2.0 and OpenAPI 3.0 formats";
        } catch (IllegalArgumentException e) {
            // Keep bad user input unwrapped so the controller can return HTTP 400.
            LOG.error("Failed to import mcp config: {}", request.getProjectName(), e);
            throw e;
        } catch (IOException e) {
            LOG.error("Failed to import mcp config: {}", request.getProjectName(), e);
            throw new RuntimeException("Import mcp server config failed: " + e.getMessage(), e);
        }

    }

    private List<McpToolsRegisterDTO> buildMcpToolRegisterDTO(final String swaggerJson, final String namespaceId) {
        ArrayList<McpToolsRegisterDTO> mcpToolsRegisterDTOList = new ArrayList<>();
        OpenAPI openapi = new OpenAPIV3Parser().readContents(swaggerJson, null, null).getOpenAPI();
        Map<String, List<Map<String, ShenyuMcpTool>>> mcpToolMap = buildShenyuMcpTool(openapi);
        JsonObject openApiJsonObject = JsonParser.parseString(swaggerJson).getAsJsonObject();
        mcpToolMap.forEach((selectorName, mcpToolList) -> {
            mcpToolList.forEach(shenyuMcpToolMap -> {
                shenyuMcpToolMap.forEach((url, shenyuMcpTool) -> {
                    McpToolsRegisterDTO mcpToolsRegisterDTO = McpToolsRegisterDTOGenerator.generateRegisterDTO(shenyuMcpTool, openApiJsonObject, url, namespaceId);

                    mcpToolsRegisterDTO.setMetaDataRegisterDTO(buildMetaDataRegisterDTO(openapi, selectorName, shenyuMcpTool, url, namespaceId));
                    mcpToolsRegisterDTOList.add(mcpToolsRegisterDTO);
                });
            });

View on GitHub (pinned to 567142e072)