LlamaIndex — every error, fix, and pattern

What is LlamaIndex?

LlamaIndex is the RAG-first open-source framework for building applications on top of LLMs. Where LangChain emphasizes composable chains and agents, LlamaIndex emphasizes data — indexing, retrieval, and query engines as first-class primitives. It has particularly strong support for advanced retrieval patterns (router, sub-question, hybrid) and its own event-driven Workflow orchestration.

This hub focuses on the errors, gotchas, and configuration issues that come up in production LlamaIndex code — not tutorial content. Every guide has real error messages, ranked causes, three tested fixes with working code, and prevention checklists.

Browse by category

Every LlamaIndex error we've documented, grouped into the six categories that matter for troubleshooting.

All 15 LlamaIndex errors

The complete list — sorted by page number. Each fix guide includes real error messages, root causes ranked by frequency, three tested fixes with working Python code, a seven-item prevention checklist, and five FAQs.

• #106
  VectorStoreIndex construction — embedding batches fail

  Core Query Engine & Ingestion
  n/a
• #107
  SimpleDirectoryReader — file type and encoding errors

  Core Query Engine & Ingestion
  n/a
• #108
  Node parser selection — SentenceSplitter vs Semantic vs Code

  Core Query Engine & Ingestion
  n/a
• #109
  Query engine returning empty or wrong nodes

  Core Query Engine & Ingestion
  n/a
• #110
  Chat engine mode selection — Condense, Context, or plus

  Chat Engines & Agents
  n/a
• #111
  Agents — ReActAgent and FunctionCallingAgent

  Chat Engines & Agents
  n/a
• #112
  Workflow @step, Event, and Context errors

  Chat Engines & Agents
  n/a
• #113
  RouterQueryEngine — selector picks wrong engine

  Advanced Retrieval
  n/a
• #114
  SubQuestionQueryEngine — decomposition errors

  Advanced Retrieval
  n/a
• #115
  Hybrid retrieval — QueryFusionRetriever and RRF

  Advanced Retrieval
  n/a
• #116
  StorageContext mismatch — wrong embed_model on reload

  Storage & Persistence
  n/a
• #117
  Vector store integrations — Chroma, Qdrant, Pinecone

  Storage & Persistence
  n/a
• #118
  Settings global vs per-object resolution

  Config & Integration
  n/a
• #119
  Evaluation modules — cost blowup and sampling

  Evaluation & Observability
  n/a
• #120
  Observability — instrumentation, Arize, Langfuse, LlamaCloud

  Evaluation & Observability
  n/a

LlamaIndex package catalog (2026)

LlamaIndex is a family of independently versioned packages. Core primitives live in llama-index-core; every integration (embedding provider, LLM, vector store) has its own package.

Core patterns to know

Six patterns that come up in almost every LlamaIndex codebase — and where each one goes wrong.

• Durable ingestion with IngestionPipeline + docstore. Skip the one-liner tutorials. See VectorStoreIndex batch failures.
• Query engine tuning — similarity_top_k, response mode, filters. See query engine returning wrong nodes.
• Advanced retrieval — Router for domain routing; SubQuestion for decomposition; QueryFusion for hybrid. See hybrid retrieval.
• Workflow orchestration — event-driven state machines for complex agents. See Workflow errors.
• Storage persistence — persist_dir + embed_model config together. See StorageContext mismatch.
• Explicit models — never trust global Settings in production. See Settings resolution.