[Bug] Z.AI APIs (completion & anthropic) crash when MCP tool schema declares object property $ref

提交前确认 · Pre-submission checklist

• 我已搜索过现有 issue，确认这不是重复 / I searched existing issues and confirmed this isn't a duplicate.
• 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别 · Category

工具调用 / MCP · Tool use / MCP

涉及的 Agent 框架 · Agent framework

Claude Code

严重程度 · Severity

阻塞使用 · Blocking (无法使用核心功能 / core function unusable)

复现频率 · Reproducibility

必现 · Always

问题描述 · Description

The Z.AI API server crashes reproducibly when an MCP tool schema declares an object property named $ref.

The specific example that affected me was Signoz MCP, but any similar schema will do it. Annoyingly, the failure mode is getting "Network error 1234" instead of anything that might point you in the right direction.

This makes the GLM Coding Plan unusable with Claude Code for any user whose MCP servers expose a tool with a property named $ref — and it is unusually hard to diagnose:

The error claims to be a network problem, so the first suspicion falls on the user's own proxy, gateway or connectivity.
Ordinary chat requests work perfectly, so the model, the plan and the credentials all appear healthy.
Only requests carrying the full tool list fail, and that list is not something the user normally sees.
Finding it took a full request-body capture and two rounds of bisection. An error message naming the offending tool — or simply the offending property — would have turned a multi-hour investigation into a one-minute fix.

复现步骤 · Steps to reproduce

Send this to GLM-5.3:

{
  "model": "glm-5.3",
  "max_tokens": 16,
  "stream": true,
  "tools": [{
    "name": "t",
    "description": "d",
    "input_schema": {"type": "object", "properties": {"$ref": {"type": "string"}}}
  }],
  "messages": [{"role": "user", "content": "Reply with the single word: ok"}]
}

期望表现 · Expected behavior

Not crashing :-)

实际表现 · Actual behavior

Result: HTTP 500, code 1234.

ZCode 版本 · ZCode version

N/A

设备 / 系统 / 浏览器 · Device / OS / Browser

N/A

截图 / 录屏 / 日志 · Screenshots / Recordings / Logs

09:04:37 - LiteLLM Router:INFO: router.py:4723 - ageneric_api_call_with_fallbacks(model=beelzebub) Exception {"type":"error","error":{"type":"api_error","code":"1234","message":"[1234][Network error, error id: 20260827170437d03a1a37c69443b7, please try again later][20260827170437d03a1a37c69443b7]"},"request_id":"20260827170437d03a1a37c69443b7"}
09:04:39 - LiteLLM Router:INFO: router.py:6386 - Trying to fallback b/w models
09:04:39 - LiteLLM Proxy:ERROR: endpoints.py:194 - litellm.proxy.proxy_server.anthropic_response(): Exception occured - {"type":"error","error":{"type":"api_error","code":"1234","message":"[1234][Network error, error id: 20260827170437d03a1a37c69443b7, please try again later][20260827170437d03a1a37c69443b7]"},"request_id":"20260827170437d03a1a37c69443b7"}
Traceback (most recent call last):
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 1910, in _async_post_anthropic_messages_with_http_error_retry
    response = await async_httpx_client.post(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<6 lines>...
    )
    ^
  File "/app/.venv/lib/python3.13/site-packages/litellm/litellm_core_utils/logging_utils.py", line 289, in async_wrapper
    result: Final = await func(*args, **kwargs)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/http_handler.py", line 721, in post
    await _raise_masked_async_error(e, stream)
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/http_handler.py", line 480, in _raise_masked_async_error
    raise MaskedHTTPStatusError(e, message=_body, text=_body) from None
litellm.llms.custom_httpx.http_handler.MaskedHTTPStatusError: Server error '500 Internal Server Error' for url 'https://api.z.ai/api/anthropic/v1/messages'
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6660, in async_function_with_retries
    response = await self.make_call(original_function, *args, **kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6818, in make_call
    response = await response
               ^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 4730, in _ageneric_api_call_with_fallbacks_helper
    raise e
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 4716, in _ageneric_api_call_with_fallbacks_helper
    response = await response
               ^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/utils.py", line 1951, in wrapper_async
    raise e
  File "/app/.venv/lib/python3.13/site-packages/litellm/utils.py", line 1760, in wrapper_async
    result = await original_function(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/anthropic/experimental_pass_through/messages/handler.py", line 357, in anthropic_messages
    response = await init_response
               ^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 2145, in async_anthropic_messages_handler
    response: Final = await self._async_post_anthropic_messages_with_http_error_retry(
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<16 lines>...
    )
    ^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 1945, in _async_post_anthropic_messages_with_http_error_retry
    raise self._handle_error(e=e, provider_config=provider_config)
          ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 5755, in _handle_error
    raise provider_config.get_error_class(
    ...<3 lines>...
    )
litellm.llms.base_llm.chat.transformation.BaseLLMException: {"type":"error","error":{"type":"api_error","code":"1234","message":"[1234][Network error, error id: 202608271704342fd3151178594e70, please try again later][202608271704342fd3151178594e70]"},"request_id":"202608271704342fd3151178594e70"}

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/app/.venv/lib/python3.13/site-packages/litellm/proxy/anthropic_endpoints/endpoints.py", line 97, in anthropic_response
    result: Final = await base_llm_response_processor.base_process_llm_request(
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<16 lines>...
    )
    ^
  File "/app/.venv/lib/python3.13/site-packages/litellm/proxy/common_request_processing.py", line 1911, in base_process_llm_request
    responses = await llm_responses
                ^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 5959, in async_wrapper
    return await self._ageneric_api_call_with_fallbacks(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<2 lines>...
    )
    ^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 4609, in _ageneric_api_call_with_fallbacks
    raise e
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 4596, in _ageneric_api_call_with_fallbacks
    response: Final = await self.async_function_with_fallbacks(**kwargs)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6567, in async_function_with_fallbacks
    return await self.async_function_with_fallbacks_common_utils(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<9 lines>...
    )
    ^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6529, in async_function_with_fallbacks_common_utils
    raise original_exception
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6558, in async_function_with_fallbacks
    response = await self.async_function_with_retries(*args, **kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6809, in async_function_with_retries
    raise original_exception
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6742, in async_function_with_retries
    response = await self.make_call(original_function, *args, **kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 6818, in make_call
    response = await response
               ^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 4730, in _ageneric_api_call_with_fallbacks_helper
    raise e
  File "/app/.venv/lib/python3.13/site-packages/litellm/router.py", line 4716, in _ageneric_api_call_with_fallbacks_helper
    response = await response
               ^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/utils.py", line 1951, in wrapper_async
    raise e
  File "/app/.venv/lib/python3.13/site-packages/litellm/utils.py", line 1760, in wrapper_async
    result = await original_function(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/anthropic/experimental_pass_through/messages/handler.py", line 357, in anthropic_messages
    response = await init_response
               ^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 2145, in async_anthropic_messages_handler
    response: Final = await self._async_post_anthropic_messages_with_http_error_retry(
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<16 lines>...
    )
    ^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 1945, in _async_post_anthropic_messages_with_http_error_retry
    raise self._handle_error(e=e, provider_config=provider_config)
          ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/llm_http_handler.py", line 5755, in _handle_error
    raise provider_config.get_error_class(
    ...<3 lines>...
    )
litellm.llms.base_llm.chat.transformation.BaseLLMException: {"type":"error","error":{"type":"api_error","code":"1234","message":"[1234][Network error, error id: 20260827170437d03a1a37c69443b7, please try again later][20260827170437d03a1a37c69443b7]"},"request_id":"20260827170437d03a1a37c69443b7"}
INFO:     172.28.176.39:56308 - "POST /v1/messages?beta=true HTTP/1.1" 500 Internal Server Error

Start by reproducing the provided JSON request against the Z.AI /v1/messages endpoint with the MCP tool schema containing a $ref property, then compare it with a request without that property. Trace the failure through the reported Anthropic and completion API paths. Done means the request no longer returns HTTP 500 or code 1234, with a useful error if the schema remains unsupported.