-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Indexed by symptom — start here if something's behaving unexpectedly, before assuming it's a Mnemolis bug.
As of a later fix, Mnemolis distinguishes a genuine timeout from other connection failures in its own response — a timeout-specific message means exactly that, not a guess. Either way, check Health & Observability first — /health's sources.web field will show the real underlying error, which is almost always more specific and more useful than Mnemolis's own response. Two distinct real causes have actually been found and documented here:
-
Timeout set too aggressively for real engine latency. SearXNG's default
request_timeout(3.0s) is genuinely too short — several real search engines routinely take 20+ seconds to respond under completely normal conditions. See The SearXNG Timeout Lesson for the exact fix and, more importantly, for the second part of that story: a correctly-edited config file doesn't help if the container was never restarted to pick it up. If you've already made this fix and the error persists, check whether SearXNG has actually been restarted since you editedsettings.yml—docker exec searxng grep -A2 "^outgoing:" /etc/searxng/settings.ymlreads the config the live process sees, which is the only way to be sure. -
Genuine upstream rate limiting. A specific engine (Brave has been observed doing this) returning
SearxEngineTooManyRequestsExceptionafter heavy query volume. This self-resolves after the engine's own suspension window; it's not something to "fix" so much as expect under sustained testing.
If the query is phrased like current discourse ("what's the deal with X everyone's talking about/obsessed with"), this is a known, specifically-handled pattern — see The Discourse-Framing Investigation. If you're still seeing Kiwix skipped for phrasing that doesn't match that pattern, check Routing for the actual keyword-match and LLM-selection logic; the LLM genuinely can make a different call than expected for a query that's just inherently ambiguous about which source applies.
Check Kiwix Scoring first — if the word genuinely has multiple, comparably-represented senses in your index (the "galaxy" astronomy-vs-pop-culture case is the documented example), this is an accepted, real limitation of keyword-and-structure scoring, not necessarily a bug. If the query was multi-word and still landed on something nonsensical, that's more likely worth investigating — disambiguation is only supposed to trigger for genuinely single-word, definitional, Wikipedia-targeted queries.
If you're using Open WebUI or a similar tool-calling setup, check whether the calling model is actually forwarding your entire message to Mnemolis in one call, or silently splitting/truncating it itself before Mnemolis's own decomposition ever sees the full question. This is a real, repeatedly-observed failure mode at the model layer, not a Mnemolis routing bug — see the Open WebUI System Prompt Guide for the actual fix and the log-level evidence confirming it works.
If you're calling the API directly and a genuinely compound query still isn't splitting correctly, check Query Decomposition for what conjunctions are actually recognized — a conjunction Mnemolis doesn't currently watch for (anything outside "and", "also", "plus", "as well as", "in addition") won't trigger a split.
This exact category of bug has a long, real history — see The Proper-Noun-Pair Saga for the full account of five sequential bugs found in this specific logic, including one found via a deliberate code-reading investigation rather than a failing test. If you're seeing a sixth, it's worth checking whether your query combines a protected pair with adjacent real content in a way the existing fixes don't account for, or whether a different always-capitalized word (beyond the pronoun "I," already excluded) is producing a similar false positive.
Check Conditional Query Detection — detection is deliberately narrow. Missing the leading comma ("if the front door is unlocked tell me," no comma) is a known, accepted limitation, not a bug. Mid-sentence or trailing "if" is out of scope for the same reason. If the structure genuinely matches the leading-comma pattern and still isn't framed correctly, check whether the source the condition resolved to is actually one of the three interpretable sources (ha, uptime, forecast) — every other source intentionally never gets a yes/no verdict, only an honestly-presented raw result.
Almost always a Docker volume-naming mismatch, not a real failure — see Backup & Restore. Check the actual volume name Docker created (docker volume ls, or docker inspect <container>) before assuming the restore command itself is broken.
Check /health's snapshot_jobs field — see Health & Observability for what each status (ok, stale, never_ran, unknown) actually means and how the staleness threshold is calculated.
See Home Assistant Integration — a real, now-fixed bug used to cause exactly this for specific entity questions like "is the front door locked." If you're still seeing it, check that the entity actually exists and is named the way you'd expect — GET /areas lists what Mnemolis can currently see.
A source you forgot to configure returned its own raw error message instead of falling back to web search
Check Routing — kiwix and news are both supposed to fall back to web automatically when they come back empty, including when they're simply unconfigured. This used to fail silently for certain "not configured"/"could not connect" messages specifically; fixed now, but worth confirming the source you expected to fall back from is actually the intended one, since not every source has a configured fallback target.
If forecast is returning real-looking weather data that's nowhere near where you actually live, check that FORECAST_LATITUDE and FORECAST_LONGITUDE are genuinely set — leaving them blank used to silently default to (0, 0), a real, valid ocean coordinate, so the forecast would "work" without ever telling you it was answering for the wrong place on Earth. This is fixed now: an unconfigured forecast correctly returns a "not configured" message instead.
A query about a single-letter or single-digit topic (like "the C language" or "vitamin D") returns oddly generic, off-topic results
A real bug used to drop single-character search terms entirely while scoring and building search queries, since they were filtered out the same way stray punctuation is — meaning a query about "R programming" could lose the one word that actually distinguished it from any other programming language. Fixed now; single letters and digits are kept.
If FUSION_MAX_SOURCES is set to 0, this used to crash with a raw error; it now correctly reports "no valid sources specified" instead. If you're trying to limit fusion to fewer sources, set it to a positive number — 0 was never a valid way to disable fusion, just a configuration mistake that's now handled gracefully instead of crashing.
Several of the real bugs documented in Design History were only correctly diagnosed by adding genuine debug tracing and reading the actual output, rather than guessing at a plausible-sounding cause. If something's behaving unexpectedly and none of the documented cases above match, check the application logs directly (docker logs mnemolis) for the actual routing/decomposition/conditional-detection decision being made, rather than inferring it from the final response alone — the log lines at each of those stages are usually specific enough to show exactly where a query's handling diverged from what was expected.