run-llama/llama_index · error · ImportError

WandbCallbackHandler is not installed. Please install it usi

Error message

WandbCallbackHandler is not installed. Please install it using `pip install llama-index-callbacks-wandb`

What it means

Raised by create_global_handler() when global_handlers eval_mode is 'wandb' but the optional integration package llama-index-callbacks-wandb is not installed. llama-index-core keeps every observability integration as a separate optional dependency and lazily imports it only when that eval mode is selected, so a missing wheel surfaces as this ImportError at handler-creation time. The message names the exact pip package to install.

Source

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

    import llama_index.core

    handler = create_global_handler(eval_mode, **eval_params)
    if handler:
        llama_index.core.global_handler = handler


def create_global_handler(
    eval_mode: str, **eval_params: Any
) -> Optional[BaseCallbackHandler]:
    """Get global eval handler."""
    handler: Optional[BaseCallbackHandler] = None
    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":

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-callbacks-wandb
Verify the import works: python -c "from llama_index.callbacks.wandb import WandbCallbackHandler"
Pin the integration version compatible with your llama-index-core version in requirements.txt
If you did not intend W&B tracing, remove the 'wandb' eval_mode / set_global_handler call

Example fix

# before
from llama_index.core import set_global_handler
set_global_handler('wandb', project='my-project')  # ImportError

# after
# pip install llama-index-callbacks-wandb
from llama_index.core import set_global_handler
set_global_handler('wandb', project='my-project')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
wandb_available = importlib.util.find_spec('llama_index.callbacks.wandb') is not None
if not wandb_available:
    raise SystemExit('Install it: pip install llama-index-callbacks-wandb')

Try / catch

try:
    handler = create_global_handler('wandb', project='x')
except ImportError as e:
    logger.warning('W&B tracing disabled: %s', e)
    handler = None

Prevention

Declare every observability integration you enable in requirements.txt alongside llama-index-core
Run a startup import smoke test for each optional integration before setting the global handler
Gate eval-mode handlers behind config so tracing can be disabled in minimal environments

When it happens

Trigger: Setting global eval mode to wandb, e.g. Settings.callback_manager.global_handler = create_global_handler('wandb', project='x') or llama_index.core.set_global_handler('wandb'), in an environment where `pip show llama-index-callbacks-wandb` fails. The `from llama_index.callbacks.wandb import WandbCallbackHandler` import inside the try block raises ImportError and is re-raised with this message.

Common situations: Installing only llama-index-core (or the meta-package without extras) and then enabling W&B tracing; CI environments that trimmed optional deps; typo'd extras like pip install llama-index[wandb] on distributions that publish a separate callbacks wheel; upgrading llama-index and forgetting that integrations moved to independently versioned packages.

Related errors

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