Troubleshooting

This page lists concrete, source-verified failure modes — not speculative advice.

result.context is just a placeholder message

Symptom: result.context is "📚 المعلومات المسترجعة:\nلا تتوفر معلومات.\n─── نهاية السياق ───" (or the English equivalent).

Cause: SmartContextComposer.compose() was called with an empty chunks list — meaning retrieval + filtering + ranking together produced zero results.

Diagnose:

result = engine.run(query)
print(result.total_retrieved, result.total_after_filter, result.total_after_rank)

• total_retrieved == 0 → retrieval itself found nothing. Check that index()/index_documents() was called with a non-empty chunks/texts list and (if using vector search) a working embed_fn / vector_db / vector_store_adapter.
• total_retrieved > 0 but total_after_filter == 0 → FilterConfig thresholds (min_chunk_length/max_chunk_length/noise patterns) excluded everything retrieved.

result.guard_passed is False

Check result.guard_warnings — it will contain one of exactly these (verified strings from ContextGuard.validate):

• "context is empty ⚠" — see above.
• "context is too short (N characters < M)." — raise your retrieval top_k or lower GuardConfig.min_context_length.
• "context is not relevant to the query (similarity=X.XXX < Y.YY)." — only appears if check_relevance=True and an embed_fn was passed to ContextGuard. Lower relevance_threshold or investigate your embedding model/retrieval quality.

Note "context is too long" and "no valid source found in context." are warnings that do not flip guard_passed to False — they can appear even when guard_passed is True.

ValueError: weights length must equal n_queries.

Raised by WeightedBudgetAllocation.allocate(). Make sure len(weights) == n_queries exactly when constructing it directly. If you're using ComplexityBasedAllocation, this is handled for you internally as long as you pass analyses with the correct length — if it doesn't match, it falls back to equal allocation rather than raising.

ValueError: prefix_length N exceeds chunk text length M.

Raised by legacy_compat.PrefixDeduplication.deduplicate() on the first chunk shorter than prefix_length. Either lower prefix_length, filter out short chunks first, or switch to HashDeduplication (no length restriction).

AttributeError: can't set attribute

You tried config.separator = "..." or config.template = "..." directly. Both are read-only properties on ContextEngineConfig. Use config.composer.separator = "..." / config.composer.template = "..." instead.

TypeError: Can't instantiate abstract class ... with abstract method ...

You subclassed one of the strategy ABCs in strategy.py without implementing every @abstractmethod. For HybridRetrieverStrategy specifically, remember it requires both retrieve() and the method property.

from context import validate_chunk gives None

This is the documented __init__.py shadowing quirk — see API Overview. Import from the submodule instead: from context.legacy_compat import validate_chunk.

My custom composer/filter/ranker isn't being used

Verify you passed it to the correct constructor keyword: chunk_filter=, ranker=, composer=, guard=, query_analyzer=, budget_allocator=, retriever= (note retriever= expects a HybridRetriever-shaped object, while the others expect their respective *Strategy ABC). Also double check you didn't subsequently call engine.index(...) in a way that silently rebuilds a default retriever — see the warning in api/engine.md.

Performance is degrading over a long-running process

Check two things via engine.get_performance_report():

• cache.hit_rate — if low and you expect repeated queries, verify CacheConfig.enabled=True and that queries are normalized consistently (the cache key is based on the lower-cased, stripped query text plus sorted filters — small wording differences produce different keys and thus cache misses).
• VectorRetriever._query_cache grows unboundedly for the lifetime of the process (no eviction) — if you're embedding a huge number of distinct queries over a long-running process, this is an unbounded memory growth point to be aware of, separate from the bounded ContextCache. This only applies to in-memory mode (embed_fn); a native vector_db or vector_store_adapter has no client-side query cache to grow.

Need more detail?

Every class's API page includes a "Common Mistakes" section with issues specific to that component — see API Overview.