iflytek/astron-agent · error · Exception

update tool: failed to validate tool

Error message

update tool: failed to validate tool {tool.get('id')} schema, reason {json.dumps(err)}

What it means

Generic Exception raised when validate_openapi_schema returns an error for a tool's openapi_schema during update. It wraps the validator's structured error list (JSON-serialized) so the caller knows which tool failed and why.

Solutions

  1. Validate the openapi_schema locally (e.g. with openapi-spec-validator) before submitting the update and fix reported violations.
  2. Read the serialized 'err' payload in the exception — it lists the concrete validation failures to fix.
  3. Ensure the schema uses OpenAPI 3.x structure (openapi: 3.0.x, paths, components.schemas) not Swagger 2.0.
  4. Confirm the schema was not truncated or mangled in transit (compare lengths/hashes before and after upload).

Example fix

// before
raise Exception(
    f"update tool: failed to validate tool {tool.get('id')} schema, "
    f"reason {json.dumps(err)}")
// after
# fix the spec client-side first:
#   from openapi_spec_validator import validate
#   validate(json.loads(tool["openapi_schema"]))
# then resubmit; keep server-side raise but return HTTP 422 with err details
Defensive patterns

Strategy: validation

Validate before calling

from openapi_spec_validator import validate
import json
def schema_is_valid(tool: dict) -> bool:
    try:
        validate(json.loads(tool["openapi_schema"]))
        return True
    except Exception:
        return False

Try / catch

try:
    process_tools_for_update(tools, span_context)
except Exception as e:
    return error_response(422, f"schema invalid: {e}")

Prevention

When it happens

Trigger: update_version -> process_tools_for_update with a non-empty openapi_schema that fails validate_openapi_schema — invalid OpenAPI document (missing paths/info, wrong types, bad version string, unresolved $refs).

Common situations: Hand-authored or LLM-generated OpenAPI specs uploaded without validation; specs written against OpenAPI 2.0 (Swagger) syntax submitted to a 3.x validator; schema truncated by size limits or encoding issues.

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

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

Appendix: source

Thrown at core/plugin/link/service/community/tools/http/management_server.py:295

def process_tools_for_update(
    tools: List[Dict[str, Any]], app_id: Optional[str], span_context: Any
) -> Tuple[Optional[List[Dict[str, Any]]], List[str]]:
    """Process tools for update, including validation."""
    update_tool = []
    tool_ids = []

    for tool in tools:
        # Validate required fields
        required_fields = ["version", "name", "description", "openapi_schema"]
        for field in required_fields:
            if field not in tool:
                raise Exception(f"no {field} attr found in tool info!")

        schema_content = tool.get("openapi_schema", "")
        if schema_content:
            validated_schema, err = validate_openapi_schema(tool, span_context)
            if err:
                raise Exception(
                    f"update tool: failed to validate tool {tool.get('id')} schema, "
                    f"reason {json.dumps(err)}"
                )
            schema_content = validated_schema

        update_tool.append(
            {
                "app_id": app_id,
                "tool_id": tool.get("id"),
                "name": tool.get("name"),
                "description": tool.get("description"),
                "open_api_schema": schema_content,
                "version": tool.get("version", const.DEF_VER),
                "is_deleted": const.DEF_DEL,
            }
        )
        tool_ids.append(tool.get("id") or "")

View on GitHub (pinned to 5e758547a8)