run-llama/llama_index · error · ImportError

OpenInferenceCallbackHandler is not installed. Please instal

Error message

OpenInferenceCallbackHandler is not installed. Please install it using `pip install llama-index-callbacks-openinference`

What it means

Raised by create_global_handler() when eval_mode is 'openinference' but llama-index-callbacks-openinference is missing. The OpenInference handler (used to export LLM traces in OpenInference format for downstream analysis tools) is an optional extra, imported lazily inside a try/except that converts the raw ImportError into an actionable message.

Source

Thrown at llama-index-core/llama_index/core/callbacks/global_handlers.py:38

    if eval_mode == "wandb":
        try:
            from llama_index.callbacks.wandb import (
                WandbCallbackHandler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "WandbCallbackHandler is not installed. "
                "Please install it using `pip install llama-index-callbacks-wandb`"
            )

        handler = WandbCallbackHandler(**eval_params)
    elif eval_mode == "openinference":
        try:
            from llama_index.callbacks.openinference import (
                OpenInferenceCallbackHandler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "OpenInferenceCallbackHandler is not installed. "
                "Please install it using `pip install llama-index-callbacks-openinference`"
            )

        handler = OpenInferenceCallbackHandler(**eval_params)
    elif eval_mode == "arize_phoenix":
        try:
            from llama_index.callbacks.arize_phoenix import (
                arize_phoenix_callback_handler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "ArizePhoenixCallbackHandler is not installed. "
                "Please install it using `pip install llama-index-callbacks-arize-phoenix`"
            )

        handler = arize_phoenix_callback_handler(**eval_params)
    elif eval_mode == "honeyhive":

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-callbacks-openinference
Confirm with: python -c "from llama_index.callbacks.openinference import OpenInferenceCallbackHandler"
Pin the package version alongside llama-index-core in your lockfile
Disable the openinference eval mode if tracing was not intended

Example fix

# before
set_global_handler('openinference')  # ImportError

# after
# pip install llama-index-callbacks-openinference
set_global_handler('openinference')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('llama_index.callbacks.openinference') is None:
    raise SystemExit('pip install llama-index-callbacks-openinference')

Try / catch

try:
    handler = create_global_handler('openinference')
except ImportError as e:
    handler = None  # tracing optional

Prevention

Add optional callback extras to the project lockfile when enabling them
Docker/CI images should install the same extras as local dev to catch missing wheels early

When it happens

Trigger: Calling create_global_handler('openinference', ...) or set_global_handler('openinference') without the package installed; the lazy import `from llama_index.callbacks.openinference import OpenInferenceCallbackHandler` fails and the except ImportError branch re-raises with this text.

Common situations: Enabling OpenInference tracing after copying example code that assumes the extra is present; minimal Docker images that only install llama-index-core; version drift after splitting integrations into separate wheels.

Related errors

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