run-llama/llama_index · critical · ValueError

ServiceContext is deprecated. Use llama_index.settings.Setti

Error message

ServiceContext is deprecated. Use llama_index.settings.Settings instead, or pass in modules to local functions/methods/interfaces.\nSee the docs for updated usage/migration: \nhttps://docs.llamaindex.ai/en/stable/module_guides/supporting_modules/service_context_migration/

What it means

ServiceContext was the pre-settings dependency container and is fully removed: its __init__ unconditionally raises a ValueError pointing at the Settings singleton and the migration docs. Any instantiation — including ServiceContext.from_defaults — fails by design in current llama-index versions.

Source

Thrown at llama-index-core/llama_index/core/service_context.py:14

from typing import Any, Optional


class ServiceContext:
    """
    Service Context container.

    NOTE: Deprecated, use llama_index.settings.Settings instead or pass in
    modules to local functions/methods/interfaces.

    """

    def __init__(self, **kwargs: Any) -> None:
        raise ValueError(
            "ServiceContext is deprecated. Use llama_index.settings.Settings instead, "
            "or pass in modules to local functions/methods/interfaces.\n"
            "See the docs for updated usage/migration: \n"
            "https://docs.llamaindex.ai/en/stable/module_guides/supporting_modules/service_context_migration/"
        )

    @classmethod
    def from_defaults(
        cls,
        **kwargs: Any,
    ) -> "ServiceContext":
        """
        Create a ServiceContext from defaults.

        NOTE: Deprecated, use llama_index.settings.Settings instead or pass in
        modules to local functions/methods/interfaces.

        """

View on GitHub (pinned to afd0fef371)

Solutions

Replace ServiceContext usage with the global Settings object (Settings.llm, Settings.embed_model, Settings.node_parser) or pass modules directly to constructors
Remove all service_context= arguments from index/query-engine construction
Update pinned third-party packages to versions compatible with llama-index >= 0.10
Follow the migration guide referenced in the error message

Example fix

# before
from llama_index.core import ServiceContext
ctx = ServiceContext.from_defaults(llm=llm, embed_model=embed_model)
index = VectorStoreIndex.from_documents(docs, service_context=ctx)

# after
from llama_index.core import Settings, VectorStoreIndex
Settings.llm = llm
Settings.embed_model = embed_model
index = VectorStoreIndex.from_documents(docs)

Defensive patterns

Strategy: validation

Validate before calling

# before importing old code, check compatibility
import llama_index.core
from packaging.version import parse
assert parse(llama_index.core.__version__.split("+")[0]) >= parse("0.10.0"), "need >=0.10 Settings API"

Prevention

Migrate to the global Settings singleton (Settings.llm, Settings.embed_model)
Pass modules directly to constructors instead of a context object
Upgrade or replace packages that still import ServiceContext
Run the 0.10 migration guide against legacy notebooks before upgrading

When it happens

Trigger: Calling ServiceContext(...), ServiceContext.from_defaults(...), or any old tutorial/API that passes service_context=... into indices, retrievers, or query engines.

Common situations: Upgrading from llama_index <0.10 to >=0.10; running legacy notebooks/blog code; third-party packages still importing ServiceContext.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/9166c5855387175f. Report an issue: GitHub.