run-llama/llama_index · error · ImportError

ArizePhoenixCallbackHandler is not installed. Please install

Error message

ArizePhoenixCallbackHandler is not installed. Please install it using `pip install llama-index-callbacks-arize-phoenix`

What it means

Raised by create_global_handler() when eval_mode is 'arize_phoenix' but llama-index-callbacks-arize-phoenix is absent. The Arize Phoenix tracing integration is optional; the lazy import of arize_phoenix_callback_handler is wrapped in try/except ImportError and re-raised with the exact install command.

Source

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

    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":
        try:
            from llama_index.callbacks.honeyhive import (
                honeyhive_callback_handler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "HoneyHiveCallbackHandler is not installed. "
                "Please install it using `pip install llama-index-callbacks-honeyhive`"
            )
        handler = honeyhive_callback_handler(**eval_params)
    elif eval_mode == "promptlayer":
        try:

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-callbacks-arize-phoenix
Verify: python -c "from llama_index.callbacks.arize_phoenix import arize_phoenix_callback_handler"
Also run a Phoenix server/endpoint if you actually want trace collection
Remove the arize_phoenix eval mode if unused

Example fix

# before
set_global_handler('arize_phoenix')  # ImportError

# after
# pip install llama-index-callbacks-arize-phoenix
set_global_handler('arize_phoenix')

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try:
    handler = create_global_handler('arize_phoenix')
except ImportError as e:
    logger.warning('Phoenix tracing off: %s', e)
    handler = None

Prevention

Treat observability integrations as first-class dependencies in deployment manifests
Verify optional imports in a pre-deploy check script

When it happens

Trigger: create_global_handler('arize_phoenix', ...) or set_global_handler('arize_phoenix') in an environment lacking the wheel; the inner `from llama_index.callbacks.arize_phoenix import arize_phoenix_callback_handler` import fails.

Common situations: Following Phoenix quickstarts that assume pip install arize-phoenix also installed the LlamaIndex integration (it did not); new environments provisioned from a bare llama-index-core requirement.

Related errors

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