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: restore quick-mode error report guidance (#7239)

Chanhyo Jung899f04dc52aa
diff --git a/changelog.d/7235.bugfix.md b/changelog.d/7235.bugfix.md
new file mode 100644
index 0000000000..67b68c05a9
--- /dev/null
+++ b/changelog.d/7235.bugfix.md
@@ -0,0 +1 @@
+Quick-mode error reports now provide actionable guidance for context limits, timeouts, rate limits, connection failures, and LLM synthesis failures without exposing private error details.
diff --git a/src/local_deep_research/error_handling/report_generator.py b/src/local_deep_research/error_handling/report_generator.py
index 6387abb019..a3f4f2d44b 100644
--- a/src/local_deep_research/error_handling/report_generator.py
+++ b/src/local_deep_research/error_handling/report_generator.py
@@ -469,6 +469,36 @@ We're here to help you get this working:
"- Ensure the service port isn't blocked by firewall\n"
"- Alternative: Use host networking mode (see wiki for setup)"
),
+ "token limit|context length": (
+ "The research exceeded the model's context limit.\n\n"
+ "**Try this:**\n"
+ "- Reduce the research scope or number of search iterations\n"
+ "- Try a model with a larger context window"
+ ),
+ "timeout|timed out": (
+ "The LLM request took too long to complete.\n\n"
+ "**Try this:**\n"
+ "- Retry after checking that your LLM service is running\n"
+ "- Reduce the research scope or increase the request timeout"
+ ),
+ "rate limit": (
+ "The research reached the LLM provider's request limit.\n\n"
+ "**Try this:**\n"
+ "- Wait a few minutes before retrying\n"
+ "- Reduce concurrent research requests or check your provider's quota"
+ ),
+ "connection|network": (
+ "The connection to the LLM service failed.\n\n"
+ "**Try this:**\n"
+ "- Check your network connection and that the LLM service is running\n"
+ "- Verify the service address in settings, then retry"
+ ),
+ "llm error|final answer synthesis fail": (
+ "The language model could not complete the final answer.\n\n"
+ "**Try this:**\n"
+ "- Check that your LLM service is running, then retry\n"
+ "- Try a different model or reduce the research scope"
+ ),
}
# Check each pattern and replace if found
diff --git a/tests/error_handling/test_report_generator_disclosure.py b/tests/error_handling/test_report_generator_disclosure.py
index 034a6640aa..ed4d9c3140 100644
--- a/tests/error_handling/test_report_generator_disclosure.py
+++ b/tests/error_handling/test_report_generator_disclosure.py
@@ -69,3 +69,158 @@ def test_report_skips_error_shaped_partial_knowledge():
)
assert marker not in report
+
+
+ "uppercase", [False, True], ids=["original", "uppercase"]
+)
+ ("error_message", "explanation", "recovery"),
+ [
+ pytest.param(
+ "Error: final answer synthesis failed: context length exceeded",
+ "model's context limit",
+ "Reduce the research scope",
+ id="context-length",
+ ),
+ pytest.param(
+ "Error: token limit exceeded",
+ "model's context limit",
+ "Reduce the research scope",
+ id="token-limit",
+ ),
+ pytest.param(
+ "Error: Request timed out after 120s",
+ "request took too long",
+ "increase the request timeout",
+ id="timed-out",
+ ),
+ pytest.param(
+ "Error: timeout during synthesis",
+ "request took too long",
+ "increase the request timeout",
+ id="timeout",
+ ),
+ pytest.param(
+ "Error: rate limit exceeded (429)",
+ "provider's request limit",
+ "Wait a few minutes",
+ id="rate-limit",
+ ),
+ pytest.param(
+ "Error: connection lost during synthesis",
+ "connection to the LLM service failed",
+ "Check your network connection",
+ id="connection",
+ ),
+ pytest.param(
+ "Error: network unavailable",
+ "connection to the LLM service failed",
+ "Check your network connection",
+ id="network",
+ ),
+ pytest.param(
+ "Error: LLM error during synthesis",
+ "language model could not complete",
+ "Try a different model",
+ id="llm-error",
+ ),
+ pytest.param(
+ "Error: final answer synthesis failed",
+ "language model could not complete",
+ "Try a different model",
+ id="synthesis-failed",
+ ),
+ ],
+)
+def test_report_gives_safe_recovery_for_quick_mode_failures(
+ error_message: str, explanation: str, recovery: str, uppercase: bool
+) -> None:
+ if uppercase:
+ error_message = error_message.upper()
+ raw_error = (
+ f"{error_message} /srv/private/provider-internals.txt"
+ " | Details: private-details-7235 https://provider.private.test/v1"
+ )
+
+ report = ErrorReportGenerator().generate_error_report(
+ raw_error, "research query"
+ )
+
+ what_happened = report.split("**What happened:** ", 1)[1].split(
+ "\n*For detailed error information", 1
+ )[0]
+ assert explanation.lower() in what_happened.lower()
+ assert recovery.lower() in what_happened.lower()
+ assert "**Try this:**" in what_happened
+ assert error_message not in report
+ assert raw_error not in report
+ assert "/srv/private/provider-internals.txt" not in report
+ assert "private-details-7235" not in report
+ assert "https://provider.private.test/v1" not in report
+ assert "| Details:" not in report
+
+
+ ("error_message", "expected_message"),
+ [
+ pytest.param(
+ "Error: connection refused during final answer synthesis failed",
+ "Cannot connect to the LLM service.",
+ id="specific-connection",
+ ),
+ pytest.param(
+ "Error: All search engines blocked and rate limited",
+ "No search results were found for your query.",
+ id="specific-search",
+ ),
+ pytest.param(
+ "Error: TypeError Context Size; context length exceeded",
+ "Model configuration issue.",
+ id="specific-context",
+ ),
+ pytest.param(
+ "Error: timeout (Error type: openai_auth)",
+ "Authentication with the LLM provider failed.",
+ id="known-typed",
+ ),
+ pytest.param(
+ "Error: network unavailable (ERROR TYPE: OPENAI_TIMEOUT)",
+ "The configured LLM server timed out.",
+ id="known-typed-uppercase",
+ ),
+ pytest.param(
+ "Error: timeout (Error type: custom_provider_error)",
+ "Research failed due to an unexpected error.",
+ id="nonstandard-typed",
+ ),
+ pytest.param(
+ "Error: unexplained failure (Error type: unknown)",
+ "Research failed due to an unexpected error.",
+ id="unknown-typed",
+ ),
+ pytest.param(
+ "Error: unexplained failure",
+ "Research failed due to an unexpected error.",
+ id="unknown-untyped",
+ ),
+ ],
+)
+def test_report_preserves_message_precedence_with_private_details(
+ error_message: str, expected_message: str
+) -> None:
+ raw_error = (
+ f"{error_message} /srv/private/provider-internals.txt"
+ " | Details: private-details-7235 https://provider.private.test/v1"
+ )
+
+ report = ErrorReportGenerator().generate_error_report(
+ raw_error, "research query"
+ )
+
+ assert f"**What happened:** {expected_message}" in report
+ assert error_message not in report
+ assert "/srv/private/provider-internals.txt" not in report
+ assert "private-details-7235" not in report
+ assert "https://provider.private.test/v1" not in report
+ assert "| Details:" not in report