searxng-mcp-go/docs/adr/006-unresponsive-engines-debug-only.md
XLion 7c60300b48
docs: fix documentation inaccuracies across 7 files
- #218: Correct --language CLI help from [default: auto] to [default: ""]
- #219: Unify pageno default semantics in MCP_TOOLS.md table
- #220: Add 'Fetch metadata header' to Sec-Fetch-Dest/Site purpose rows
- #221: Replace pipe-violating echo | commands with → pseudo-flow notation
- #223: Clarify unresponsive_engines logged at debug level (slog.Debug)
- #224: Warn about http:// SEARXNG_URL triggering non-suppressible warning
- #225: Remove misleading PR #78 reference in centralization_drift_test.go

Closes #218, #219, #220, #221, #223, #224, #225
2026-06-11 02:23:03 +08:00

1.9 KiB

ADR-006: Expose unresponsive_engines Only in Debug Mode

Date: 2026-04-19 Status: Accepted

Context

SearXNG's JSON response includes an unresponsive_engines field listing engines that failed to respond (e.g., rate-limited, CAPTCHA, connection errors). During code review, it was identified that SearchResponse does not model this field.

Decision

Expose unresponsive_engines in the response, but only when debug mode is enabled.

In normal output (CLI and MCP), the field is omitted. When --debug or DEBUG=1 is set, the field is included in JSON output and logged at debug level in CLI stderr output.

Rationale

  1. SearXNG's nature: SearXNG's core purpose is reverse-engineering search engine interfaces. It inherently calls multiple engines simultaneously, and engine breakage (rate-limiting, CAPTCHA, API changes) is an expected and routine occurrence — not a user-caused problem.
  2. Not user-responsibility: When an engine becomes unresponsive, the fault lies with SearXNG's engine adapter (outdated scraping logic, missing CAPTCHA bypass, etc.), not with the user's query or configuration. There is no actionable step for the end user.
  3. Useful for troubleshooting, not for end users: Regular users and AI agents do not need to know which engines failed. This is diagnostic information for SearXNG operators and developers.
  4. Debug mode is the right filter: Debug mode already shows HTTP request/response details. Including engine failures here is consistent with the debug UX.

Consequences

  • SearchResponse gains an UnresponsiveEngines field with json:",omitempty" tag.
  • Search response normalization and output formatting conditionally include/exclude the field based on debug mode.
  • CLI debug output logs unresponsive engines at slog.Debug level (visible only with --debug or DEBUG=1).
  • MCP JSON output includes the field only when debug is active.