iflytek/astron-agent · error · BusinessException

WORKFLOW_MCP_SERVER_REGISTRY_FAILED

WORKFLOW_MCP_SERVER_REGISTRY_FAILED

Error message

WORKFLOW_MCP_SERVER_REGISTRY_FAILED

What it means

Thrown by WorkflowService when reading the MCP server definition file fails during MCP-Server registration. The code reads a JSON file from mcpServerFilePath and parses entries; any IOException while reading the file is logged and converted to WORKFLOW_MCP_SERVER_REGISTRY_FAILED.

Solutions

  1. Verify mcpServerFilePath is configured correctly and the file exists on the service host/container
  2. Check file read permissions for the service user
  3. Confirm the config/volume mounting (docker-compose or helm) includes the MCP server definitions file
  4. Re-deploy or restore the missing file, then retry the registration

Example fix

// before: registration assumes file exists
List<JSONObject> jsonObjects = readMcpServerFile(mcpServerFilePath);
// after: check before invoking registration flow
File f = new File(mcpServerFilePath);
if (!f.isFile() || !f.canRead()) {
    log.error("MCP server definition file missing or unreadable: {}", mcpServerFilePath);
    return;
}
List<JSONObject> jsonObjects = readMcpServerFile(mcpServerFilePath);
Defensive patterns

Strategy: validation

Validate before calling

File f = new File(mcpServerFilePath);
if (!f.isFile() || !f.canRead()) {
    throw new IllegalStateException("MCP server definition file missing/unreadable: " + mcpServerFilePath);
}

Try / catch

try {
    workflowService.registerMcpServers();
} catch (BusinessException e) {
    if ("WORKFLOW_MCP_SERVER_REGISTRY_FAILED".equals(e.getCode())) {
    // verify file path config and volume mount, then retry
    }
}

Prevention

When it happens

Trigger: MCP-Server registration runs while the configured mcpServerFilePath does not exist, is unreadable (permissions), points to a directory, or the underlying stream/reader throws an IOException (disk I/O error, missing mount).

Common situations: Deployment missing the MCP server definition file; wrong file path in configuration; Kubernetes/Docker volume not mounted; file permission changed after deploy.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/1d563643b49403d8. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/workflow/WorkflowService.java:5906

        List<JSONObject> jsonObjects = new ArrayList<>();
        PathMatchingResourcePatternResolver resolver = new PathMatchingResourcePatternResolver();

        // Read all JSON files under the path
        org.springframework.core.io.Resource[] resources = null;
        try {
            resources = resolver.getResources(mcpServerFilePath + "/*.json");

            for (org.springframework.core.io.Resource resource : resources) {
                try (InputStream inputStream = resource.getInputStream()) {
                    // Read file content and convert to JSONObject;
                    JSONObject jsonObject = JSON.parseObject(inputStream, JSONObject.class);

                    jsonObjects.add(jsonObject);
                }
            }
        } catch (IOException e) {
            log.error("Failed to read file for MCP-Server registration, file path={}", mcpServerFilePath, e);
            throw new BusinessException(ResponseEnum.WORKFLOW_MCP_SERVER_REGISTRY_FAILED);
        }

        return jsonObjects;
    }

    public void removeAllCanvasHold() {
        // Clear canvas multi-open count
        Long wc = count(Wrappers.lambdaQuery(Workflow.class).eq(Workflow::getDeleted, false));
        Long l = redisUtil.removeScan("spark_bot:workflow:canvas_heartbeat:*", Math.toIntExact(wc));
        log.info("remove all canvas count {}", l);
    }
}

View on GitHub (pinned to 5e758547a8)