What causes "This class is deprecated. Use any LLM class directly." in run-llama/llama_index?

Replace LLMPredictor(...) with a direct LLM instance such as OpenAI(model='gpt-4o-mini') and set Settings.llm = llm.

run-llama/llama_index · error · ValueError

This class is deprecated. Use any LLM class directly.

Error message

This class is deprecated. Use any LLM class directly.

What it means

LLMPredictor.__init__ is a hard-removal stub: constructing this deprecated wrapper always raises. Since llama-index v0.10 an LLM instance (e.g. OpenAI, Anthropic) is used directly and configured via Settings.llm or an llm= argument; the predictor layer no longer exists.

Source

Thrown at llama-index-core/llama_index/core/service_context_elements/llm_predictor.py:83

    async def astream(
        self, prompt: BasePromptTemplate, **prompt_args: Any
    ) -> TokenAsyncGen:
        """Async predict the answer to a query."""


class LLMPredictor(BaseLLMPredictor):
    """
    LLM predictor class.

    NOTE: Deprecated. Use any LLM class directly.
    """

    def __init__(
        self,
        **kwargs: Any,
    ) -> None:
        """Initialize params."""
        raise ValueError("This class is deprecated. Use any LLM class directly.")

View on GitHub (pinned to afd0fef371)

Solutions

Replace LLMPredictor(...) with a direct LLM instance such as OpenAI(model='gpt-4o-mini') and set Settings.llm = llm.
Where llm_predictor was passed into an index/query call, pass llm=<instance> instead.
For token/cost accounting that LLMPredictor used to provide, use the callbacks mechanism (TokenCountingHandler) instead.
Upgrade any third-party package that still instantiates LLMPredictor.

Example fix

# before
from llama_index.core.service_context_elements.llm_predictor import LLMPredictor
llm_predictor = LLMPredictor(llm=OpenAI(temperature=0))

# after
from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
Settings.llm = OpenAI(temperature=0)

Defensive patterns

Strategy: try-catch

Try / catch

try:
    LLMPredictor()
except ValueError as e:
    if 'deprecated' in str(e):
        Settings.llm = OpenAI()  # use an LLM class directly
    else:
        raise

Prevention

Use concrete LLM classes (OpenAI, Anthropic, etc.) and Settings.llm; never import service_context_elements.llm_predictor.
Use TokenCountingHandler callbacks for token accounting previously done by LLMPredictor.
Add a lint rule forbidding LLMPredictor imports.

When it happens

Trigger: Instantiating LLMPredictor(...) or LLMPredictor(), often as service_context=ServiceContext.from_defaults(llm_predictor=LLMPredictor(...)) in pre-0.10 code, or via a dependency that wraps LLM calls through the old predictor abstraction.

Common situations: Upgrading from llama_index < 0.10, reusing old tutorial/notebook code that predates the predictor removal, or internal wrappers that standardized on LLMPredictor for prompt handling and token accounting.

Related errors

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