From 556b631c5414161a5639359ff99119a6e1eb4734 Mon Sep 17 00:00:00 2001
From: -LAN- <laipz8200@outlook.com>
Date: Wed, 15 Oct 2025 09:42:22 +0800
Subject: [PATCH] Normalize null metadata handling in tool entities (#26890)

---
 api/core/tools/entities/tool_entities.py      | 10 +++++++
 .../core/tools/test_tool_entities.py          | 29 +++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 api/tests/unit_tests/core/tools/test_tool_entities.py

diff --git a/api/core/tools/entities/tool_entities.py b/api/core/tools/entities/tool_entities.py
index 62e3aa8b5d..15a4f0aafd 100644
--- a/api/core/tools/entities/tool_entities.py
+++ b/api/core/tools/entities/tool_entities.py
@@ -189,6 +189,11 @@ class ToolInvokeMessage(BaseModel):
         data: Mapping[str, Any] = Field(..., description="Detailed log data")
         metadata: Mapping[str, Any] = Field(default_factory=dict, description="The metadata of the log")
 
+        @field_validator("metadata", mode="before")
+        @classmethod
+        def _normalize_metadata(cls, value: Mapping[str, Any] | None) -> Mapping[str, Any]:
+            return value or {}
+
     class RetrieverResourceMessage(BaseModel):
         retriever_resources: list[RetrievalSourceMetadata] = Field(..., description="retriever resources")
         context: str = Field(..., description="context")
@@ -376,6 +381,11 @@ class ToolEntity(BaseModel):
     def set_parameters(cls, v, validation_info: ValidationInfo) -> list[ToolParameter]:
         return v or []
 
+    @field_validator("output_schema", mode="before")
+    @classmethod
+    def _normalize_output_schema(cls, value: Mapping[str, object] | None) -> Mapping[str, object]:
+        return value or {}
+
 
 class OAuthSchema(BaseModel):
     client_schema: list[ProviderConfig] = Field(
diff --git a/api/tests/unit_tests/core/tools/test_tool_entities.py b/api/tests/unit_tests/core/tools/test_tool_entities.py
new file mode 100644
index 0000000000..a5b7e8a9a3
--- /dev/null
+++ b/api/tests/unit_tests/core/tools/test_tool_entities.py
@@ -0,0 +1,29 @@
+from core.tools.entities.common_entities import I18nObject
+from core.tools.entities.tool_entities import ToolEntity, ToolIdentity, ToolInvokeMessage
+
+
+def _make_identity() -> ToolIdentity:
+    return ToolIdentity(
+        author="author",
+        name="tool",
+        label=I18nObject(en_US="Label"),
+        provider="builtin",
+    )
+
+
+def test_log_message_metadata_none_defaults_to_empty_dict():
+    log_message = ToolInvokeMessage.LogMessage(
+        id="log-1",
+        label="Log entry",
+        status=ToolInvokeMessage.LogMessage.LogStatus.START,
+        data={},
+        metadata=None,
+    )
+
+    assert log_message.metadata == {}
+
+
+def test_tool_entity_output_schema_none_defaults_to_empty_dict():
+    entity = ToolEntity(identity=_make_identity(), output_schema=None)
+
+    assert entity.output_schema == {}