alibaba/nacos · error · RuntimeException

Failed to convert to endpoint spec

Error message

Failed to convert to endpoint spec

What it means

Thrown by McpServerImportService.generateEndpointSpec when converting the first FrontEndpointConfig of an imported MCP server into an McpEndpointSpec fails for any reason. The original exception is logged and rethrown as a RuntimeException, aborting the import of that server.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/McpServerImportService.java:320

    private McpEndpointSpec generateEndpointSpec(McpServerDetailInfo server) {
        if (AiConstants.Mcp.MCP_PROTOCOL_STDIO.equals(server.getProtocol())) {
            return null;
        }
        
        if (server.getRemoteServerConfig() == null
            || CollectionUtils
                .isEmpty(server.getRemoteServerConfig().getFrontEndpointConfigList())) {
            return null;
        }
        
        try {
            FrontEndpointConfig first = server.getRemoteServerConfig()
                .getFrontEndpointConfigList()
                .get(0);
            return McpConfigUtils.convertFrontEndpointConfig(first);
        } catch (Exception e) {
            LOG.error("Failed to convert to endpoint spec", e);
            throw new RuntimeException("Failed to convert to endpoint spec", e);
        }
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Inspect the imported server's frontEndpointConfigList[0] for a valid host:port endpointData and type.
2. Pre-validate endpoint fields (address, port, type) before triggering the import.
3. Catch the RuntimeException per-server in the import loop and report the item as failed rather than aborting the whole batch.

Example fix

// before
// imported server endpoint has endpointData = "not-a-valid-endpoint"

// after
FrontEndpointConfig cfg = server.getRemoteServerConfig().getFrontEndpointConfigList().get(0);
if (!cfg.getEndpointData().matches(".+:[0-9]+")) {
    reportInvalid(server, "endpointData must be host:port");
}

FrontEndpointConfig cfg = server.getRemoteServerConfig().getFrontEndpointConfigList().get(0);
if (cfg.getEndpointData() == null || !cfg.getEndpointData().matches(".+:[0-9]+")) {
    throw new IllegalArgumentException("invalid endpointData: " + cfg.getEndpointData());
}

boolean validFirstEndpoint(McpServerDetailInfo s) {
    if (s.getRemoteServerConfig() == null) return true;
    List<FrontEndpointConfig> l = s.getRemoteServerConfig().getFrontEndpointConfigList();
    if (l == null || l.isEmpty()) return true;
    String d = l.get(0).getEndpointData();
    return d != null && d.matches(".+:[0-9]+");
}

try { service.importValidatedServer(ns, item, override); }
catch (RuntimeException e) { if (e.getMessage().contains("endpoint spec")) markItemFailed(item, e); }

When it happens

Trigger: During import, a non-stdio server has a remoteServerConfig with a frontEndpointConfigList, but McpConfigUtils.convertFrontEndpointConfig(first) throws (e.g. malformed endpoint data, missing address/port, unsupported endpoint type).

Common situations: Imported registry server has an endpoint whose endpointData is not host:port; a front endpoint type the converter does not handle; address field blank or non-numeric port.

Related errors

• 10000
• 20002
• Unsupported import type: ${externalDataTypeEnum}
• URL is blank
• MCP server external id is blank

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