Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(langgraph): include exception type and translate model_dump pattern (#3926)

LearningCircuit031a2fc695fd
diff --git a/changelog.d/3926.bugfix.md b/changelog.d/3926.bugfix.md
new file mode 100644
index 0000000000..d0bcb66896
--- /dev/null
+++ b/changelog.d/3926.bugfix.md
@@ -0,0 +1 @@
+LangGraph agent strategy error messages now include the exception type, and the `'str' object has no attribute 'model_dump'` failure (issue #3897) is translated into a rich on-result-page recommendation listing the three possible causes — proxy/shim, serving stack, or model — with concrete remediation steps for each.
diff --git a/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py b/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
index 6c2280d208..ae56f4f2af 100644
--- a/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
@@ -690,7 +690,7 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
if self.collector.results:
final_content = self._synthesize_from_collector(query)
else:
- return self._error_result(f"Agent error: {exc}")
+ return self._error_result(self._format_agent_error(exc))
if not final_content:
if self.collector.results:
@@ -824,6 +824,15 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
"error": None,
}
+ @staticmethod
+ def _format_agent_error(exc: BaseException) -> str:
+ """Prefix the exception type so downstream rendering (and the
+ `ErrorReportGenerator` pattern map) have a consistent shape to match
+ on. The bare `str(exc)` produced by the catch-all loses the type,
+ which makes deep LangChain / LangGraph failures hard to recognise.
+ """
+ return f"Agent error: {type(exc).__name__}: {exc}"
+
def _error_result(self, error: str) -> Dict[str, Any]:
logger.error(f"LangGraph agent strategy error: {error}")
self._update_progress(
diff --git a/src/local_deep_research/error_handling/report_generator.py b/src/local_deep_research/error_handling/report_generator.py
index 2da06c264d..7eda3039c2 100644
--- a/src/local_deep_research/error_handling/report_generator.py
+++ b/src/local_deep_research/error_handling/report_generator.py
@@ -392,6 +392,17 @@ We're here to help you get this working:
"- **Switch model:** Use a model that supports tool calling (e.g., qwen3, gpt-oss:20b, mistral, llama3.1)\n"
"- The langgraph-agent strategy requires models with native tool/function calling support"
),
+ "model_dump|'str' object has no attribute 'model_dump'": (
+ "The agent received tool calls in a shape LangChain could not parse into structured messages. "
+ "This is a known failure mode of the **langgraph-agent** strategy when the LLM, the OpenAI-compatible server, "
+ "or a proxy in front of either of them produces non-standard tool-call responses.\n\n"
+ "**Try this:**\n"
+ "- **Bypass any proxy/shim** sitting in front of your local LLM server. Tool-call schema translation is the single most common place OpenAI-compatible proxies break, especially when they inject vendor extension fields (e.g. llama.cpp's `timings_per_token`, `return_progress`).\n"
+ "- **Update your serving stack.** llama.cpp has documented OpenAI tool-call format bugs (e.g. arguments emitted as object instead of JSON string). Recent builds of llama.cpp / vLLM / Ollama fix many of these.\n"
+ "- **Use a model with native tool-calling support.** Models without an explicit tool-call template fall back to generic prompting, which frequently produces unparseable outputs.\n"
+ "- **Switch strategy.** If you don't need an agentic loop, Settings → Search Strategy → **source-based** or **focused-iteration** sidesteps tool-calling entirely.\n"
+ "- See [issue #3897](https://github.com/LearningCircuit/local-deep-research/issues/3897) for the original report and discussion."
+ ),
"Invalid value.*SearXNG|database.*locked": (
"SearXNG configuration or rate limiting issue.\n\n"
"**Try this:**\n"
diff --git a/tests/error_handling/test_report_generator_behavior.py b/tests/error_handling/test_report_generator_behavior.py
index 5ec5bfa3a9..3d3fe15a26 100644
--- a/tests/error_handling/test_report_generator_behavior.py
+++ b/tests/error_handling/test_report_generator_behavior.py
@@ -153,6 +153,37 @@ class TestMakeErrorUserFriendly:
result = gen._make_error_user_friendly(original)
assert original in result
+ def test_model_dump_pattern_replaced(self):
+ # Issue #3897: surface a multi-cause "Try this" hint when the agent
+ # crashes with `'str' object has no attribute 'model_dump'`. The hint
+ # must name proxy/shim, server, and model as possible causes.
+ from local_deep_research.error_handling.report_generator import (
+ ErrorReportGenerator,
+ )
+
+ gen = ErrorReportGenerator()
+ result = gen._make_error_user_friendly(
+ "Agent error: AttributeError: 'str' object has no attribute 'model_dump'"
+ )
+
+ assert "LangChain could not parse" in result
+ assert "proxy/shim" in result
+ assert "Try this" in result
+ assert "issue #3897" in result
+ assert "Technical error:" in result
+
+ def test_unrelated_attribute_error_passes_through(self):
+ from local_deep_research.error_handling.report_generator import (
+ ErrorReportGenerator,
+ )
+
+ gen = ErrorReportGenerator()
+ msg = "AttributeError: 'NoneType' object has no attribute 'foo'"
+ result = gen._make_error_user_friendly(msg)
+
+ # No model_dump match → original message returned verbatim, no hint.
+ assert result == msg
+
class TestFormatPartialResults:
"""Tests for ErrorReportGenerator._format_partial_results() method."""
diff --git a/tests/strategies/test_langgraph_agent_strategy.py b/tests/strategies/test_langgraph_agent_strategy.py
index c4f701961e..da1e977a94 100644
--- a/tests/strategies/test_langgraph_agent_strategy.py
+++ b/tests/strategies/test_langgraph_agent_strategy.py
@@ -444,6 +444,16 @@ class TestErrorHandling:
assert result["error"] is not None
assert "tool calling" in result["error"]
+ def test_format_agent_error_includes_exception_type(self):
+ from local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy import (
+ LangGraphAgentStrategy,
+ )
+
+ msg = LangGraphAgentStrategy._format_agent_error(ValueError("boom"))
+
+ assert "ValueError" in msg
+ assert "boom" in msg
+
# ---------------------------------------------------------------------------
# Factory integration