run-llama/llama_index · error · ImportError

LangfuseCallbackHandler is not installed. Please install it

Error message

LangfuseCallbackHandler is not installed. Please install it using `pip install llama-index-callbacks-langfuse`

What it means

Raised by create_global_handler() when eval_mode is 'langfuse' but llama-index-callbacks-langfuse is missing. The Langfuse tracing integration is optional and imported only when selected; ImportError is re-raised with the exact package name to install.

Source

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

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

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-callbacks-langfuse
Verify: python -c "from llama_index.callbacks.langfuse import langfuse_callback_handler"
Set LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY env vars for tracing
Disable the langfuse eval mode if not needed

Example fix

# before
set_global_handler('langfuse')  # ImportError

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Note that `pip install langfuse` does not install the LlamaIndex bridge
List tracing extras in pyproject.toml optional-dependencies

When it happens

Trigger: create_global_handler('langfuse', ...) / set_global_handler('langfuse') without the wheel; `from llama_index.callbacks.langfuse import langfuse_callback_handler` raises ImportError inside the try block.

Common situations: Enabling Langfuse observability in apps deployed from slim base images; pip install langfuse alone does not provide the LlamaIndex integration; version mismatch after upgrading llama-index-core.

Related errors

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