run-llama/llama_index · error · ImportError

PromptLayerHandler is not installed. Please install it using

Error message

PromptLayerHandler is not installed. Please install it using `pip install llama-index-callbacks-promptlayer`

What it means

Raised by create_global_handler() when eval_mode is 'promptlayer' but llama-index-callbacks-promptlayer is missing. The PromptLayer callback integration is an optional dependency; selecting its eval mode triggers a lazy import that, on ImportError, is re-raised with this install hint.

Source

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

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

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-callbacks-promptlayer
Verify: python -c "from llama_index.callbacks.promptlayer import PromptLayerHandler"
Set your PromptLayer API token if you continue with tracing
Remove the promptlayer eval mode if unintended

Example fix

# before
set_global_handler('promptlayer')  # ImportError

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try:
    handler = create_global_handler('promptlayer')
except ImportError as e:
    handler = None

Prevention

Check optional extras after dependency-cache refreshes in CI
Document which eval modes your app supports and their required wheels

When it happens

Trigger: create_global_handler('promptlayer', ...) or set_global_handler('promptlayer') without the wheel; `from llama_index.callbacks.promptlayer import PromptLayerHandler` fails inside the try block.

Common situations: Adding PromptLayer tracing to an existing llama-index app without adding the new extra; environments built from a partial requirements list that predates the integrations split.

Related errors

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