iflytek/astron-agent · error · SparkLinkOpenapiSchemaException

OPENAPI_SCHEMA_SERVER_NOT_EXIST_ERR

OPENAPI_SCHEMA_SERVER_NOT_EXIST_ERR

Error message

找不到请求服务

What it means

When parsing an OpenAPI document, _validate_and_get_server_url validates the 'servers' list before extracting the base URL. If 'servers' is empty (no request servers declared), SparkLinkOpenapiSchemaException with code OPENAPI_SCHEMA_SERVER_NOT_EXIST_ERR is raised.

Solutions

1. Add a servers entry to the OpenAPI spec: servers: [{url: 'https://api.example.com/v1'}]
2. Re-export the spec from the source tool with the environment/base URL configured
3. If the spec is user-supplied, validate it before import and reject specs with empty servers with a clearer message

Example fix

// before (yaml)
servers: []
// after (yaml)
servers:
  - url: https://api.example.com/v1

def has_server(openapi: dict) -> bool:
    servers = openapi.get("servers") or []
    return len(servers) > 0 and bool(servers[0].get("url"))

try:
    parser.parse(spec)
except SparkLinkOpenapiSchemaException as e:
    if e.code == ErrCode.OPENAPI_SCHEMA_SERVER_NOT_EXIST_ERR.code:
        # prompt user to add a servers entry
        ...
    raise

When it happens

Trigger: Importing a plugin/tool whose OpenAPI spec has a 'servers' key present but an empty array, e.g. servers: []. The parser then cannot determine the base URL for requests.

Common situations: Hand-authored OpenAPI specs missing the servers section; specs generated by tools that leave servers empty; users pasting a spec exported without a configured environment/base URL.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• OPENAPI_SCHEMA_BODY_TYPE_ERR
• -1
• 21600
• -40004
• 8118

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

Appendix: source

Thrown at core/plugin/link/utils/open_api_schema/schema_parser.py:192

            # return body_schema_res
            return body_schema

    def _extract_basic_info(self, openapi: Dict[str, Any]) -> Dict[str, Any]:
        """Extract basic OpenAPI information."""
        bundles = {}
        openapi_info = openapi["info"]
        openapi_version = openapi["openapi"]
        bundles.update({"openapi_version": openapi_version})
        title = openapi_info.get("title", "")
        bundles.update({"tool_title": title})
        description = openapi_info.get("description", "")
        bundles.update({"tool_description": description})
        return bundles

    def _validate_and_get_server_url(self, openapi: Dict[str, Any]) -> str:
        """Validate server configuration and return server URL."""
        if len(openapi["servers"]) == 0:
            raise SparkLinkOpenapiSchemaException(
                code=ErrCode.OPENAPI_SCHEMA_SERVER_NOT_EXIST_ERR.code,
                err_pre=ErrCode.OPENAPI_SCHEMA_SERVER_NOT_EXIST_ERR.msg,
                err="找不到请求服务",
            )
        return openapi["servers"][0]["url"]

    def _extract_interfaces(self, openapi: Dict[str, Any]) -> List[Dict[str, Any]]:
        """Extract all interfaces from OpenAPI paths."""
        interfaces = []
        methods = ["get", "post", "put", "delete", "patch", "head", "options", "trace"]

        for path, path_item in openapi["paths"].items():
            for method in methods:
                if method in path_item:
                    interfaces.append(
                        {
                            "path": path,
                            "method": method,

View on GitHub (pinned to 5e758547a8)