run-llama/llama_index · error · ImportError

Literal AI Handler is not installed. Please install it using

Error message

Literal AI Handler is not installed. Please install it using `pip install llama-index-callbacks-literalai`

What it means

Raised by create_global_handler() when eval_mode is 'literalai' but llama-index-callbacks-literalai is not installed. The Literal AI (Langtail/Literal) tracing handler is an optional integration imported lazily; missing wheels surface as this ImportError.

Source

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

        handler = langfuse_callback_handler(**eval_params)
    elif eval_mode == "agentops":
        try:
            from llama_index.callbacks.agentops import (
                AgentOpsHandler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "AgentOpsHandler is not installed. "
                "Please install it using `pip install llama-index-instrumentation-agentops`"
            )
        AgentOpsHandler.init(**eval_params)
    elif eval_mode == "literalai":
        try:
            from llama_index.callbacks.literalai import (
                literalai_callback_handler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "Literal AI Handler is not installed. "
                "Please install it using `pip install llama-index-callbacks-literalai`"
            )
        handler = literalai_callback_handler(**eval_params)
    elif eval_mode == "opik":
        try:
            from llama_index.callbacks.opik import (
                opik_callback_handler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "Opik Handler is not installed. "
                "Please install it using `pip install llama-index-callbacks-opik`"
            )
        handler = opik_callback_handler(**eval_params)
    else:
        raise ValueError(f"Eval mode {eval_mode} not supported.")

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-callbacks-literalai
Verify: python -c "from llama_index.callbacks.literalai import literalai_callback_handler"
Provide Literal API credentials if tracing proceeds
Unset the literalai eval mode if it was enabled by mistake

Example fix

# before
set_global_handler('literalai')  # ImportError

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Mirror local and production dependency lists to catch missing extras
Version-pin all optional callback packages

When it happens

Trigger: create_global_handler('literalai', ...) or set_global_handler('literalai') in an env without the wheel; `from llama_index.callbacks.literalai import literalai_callback_handler` fails.

Common situations: Enabling Literal AI tracing per their docs in an environment that only pinned llama-index-core; CI caches missing newer integration wheels.

Related errors

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