Troubleshooting

Each entry below is grounded in an explicit error path, fallback, or docstring found in the source — not speculation about behavior that isn't observable in the code.

ImportError on from graph_rag import GraphRAG

Cause: graph_rag executes from ....chunks import DocumentChunk at import time. If the parent package structure implied by those four leading dots doesn't exist in your project, the import fails immediately — before you even construct a GraphRAG instance.

Fix: Either vendor types/graph_rag into a project where ....chunks resolves to a real module, or avoid importing graph_rag if you don't need it — the other nine subsystems import cleanly.

agentic_rag.MaxIterationsExceeded keeps being raised

Cause: AgenticRAG._decide_action is designed to force a GENERATE action at max_iterations - 1 specifically to guarantee an answer before the cap. Seeing this exception routinely suggests either max_iterations is set extremely low (e.g. 1) or the decision logic path around forced generation isn't being reached due to an unusual backend response shape.

Fix: Increase max_iterations, and confirm your rag_system.retrieve() output matches one of the shapes _normalise_docs understands (see Agentic RAG).

LLMCallError from self_improving_rag

Cause: _call_llm raises this only after every retry (retries, default 2) of llm.generate(prompt) fails.

Fix: Check the underlying llm.generate implementation for exceptions; increase SelfRAGConfig.llm_retries / RecursiveRAGConfig.llm_retries if the failures are transient (e.g. rate limits), or inspect the wrapped exception for provider-specific error details.

DomainSpecificRAG always returns the rejection message

Cause: In strict_mode=True, _measure_relevance(query) must return a score >= domain.min_relevance or the query is rejected before any retrieval happens.

Fix: Lower min_relevance, add more terms/synonyms to the DomainDefinition (via add_terms/add_synonym), or disable strict_mode if you'd rather deprioritize than block off-domain queries.

HybridSearchRAG.hybrid_search() returns empty/low-quality results

Cause: keyword_search/hybrid_search depend on train_keyword_index() having been called — BM25Scorer/TFIDFScorer must be fit() on the current document set before scoring.

Fix: Call train_keyword_index() after adding documents to the backend, and again any time the underlying corpus changes.

FederatedRAG never streams true tokens, only whole-word chunks

Cause: Per the fallback documented in FederatedRAG's streaming methods: "If no stream method is found, the federation falls back to calling generate() and re-emits the answer in small word-level fragments." supports_streaming() checks for astream → stream → generate_stream on the registered backend, in that order.

Fix: Implement one of those three method names on your rag_system to get genuine token-level streaming instead of the simulated fallback.

MultiHopRAG stops after one hop even though the question seems complex

Cause: Early stopping is intentional: once ReasoningState.confidence crosses confidence_threshold, or answer_complete becomes True, the hop loop exits regardless of max_hops.

Fix: Raise confidence_threshold, or inspect get_stats()/return_intermediate=True output to see what confidence was computed and why.

Two "TTLCache" classes behave differently / don't share entries

Cause: agentic_rag.cache.TTLCache and federated_rag.federat_cache.TTLCache are separate implementations. The agentic_rag version is explicitly documented as not thread-safe; the federated_rag version is documented as thread-safe and keyed on (query, context) rather than query alone.

Fix: Don't assume interchangeability — each subsystem manages its own cache instance internally; there's no shared cache layer across modules.

Getting non-English output when you expected English

Cause: Several modules default their language parameter to "ar" (Arabic) — ConversationalRAG(lang="ar") by default, MultiDocumentRAGSystem.query(language="ar") by default, GraphRAG.query (language="ar") by default, and StreamingRAG's default prompt_template instructs the LLM to answer in the same language as the question and never switch — so if your question is in English but a stray Arabic instruction leaks into the prompt, you may see mixed output.

Fix: Pass the language parameter explicitly wherever the API exposes one.