run-llama/llama_index · error · ValueError

Cannot add two handlers of the same type {type(new_handler)}

Error message

Cannot add two handlers of the same type {type(new_handler)} to the callback manager.

What it means

Raised by CallbackManager.__init__ when a global handler (set via llama_index.core.global_handler) has the same type as one of the handlers passed explicitly. LlamaIndex forbids two handlers of the same type in one manager to avoid double-counting traced events (e.g. duplicate token counts or spans).

Source

Thrown at llama-index-core/llama_index/core/callbacks/base.py:70

            ...
            event.on_end(payload={key, val})

    """

    def __init__(self, handlers: Optional[List[BaseCallbackHandler]] = None):
        """Initialize the manager with a list of handlers."""
        from llama_index.core import global_handler

        handlers = handlers or []

        # add eval handlers based on global defaults
        if global_handler is not None:
            new_handler = global_handler
            # go through existing handlers, check if any are same type as new handler
            # if so, error
            for existing_handler in handlers:
                if isinstance(existing_handler, type(new_handler)):
                    raise ValueError(
                        "Cannot add two handlers of the same type "
                        f"{type(new_handler)} to the callback manager."
                    )
            handlers.append(new_handler)

        # if we passed in no handlers, use the global default
        if len(handlers) == 0:
            from llama_index.core.settings import Settings

            # hidden var access to prevent recursion in getter
            cb_manager = Settings._callback_manager
            if cb_manager is not None:
                handlers = cb_manager.handlers

        self.handlers: List[BaseCallbackHandler] = handlers
        self._trace_map: Dict[str, List[str]] = defaultdict(list)

    def on_event_start(

View on GitHub (pinned to afd0fef371)

Solutions

Remove the duplicate: if a global handler of type T is set, do not also pass a T instance into CallbackManager — rely on the global one.
Clear the global handler before constructing managers with your own handler of the same type (set_global_handler(None) / unset before init).
Check for double initialization of instrumentation at startup (config reload, notebook re-runs) and guard with an if-not-already-set flag.

Example fix

# before
from llama_index.core import set_global_handler
set_global_handler("argilla")
cb = CallbackManager(handlers=[ArgillaInstrumentor().get_callback_handler()])  # duplicate type

# after
set_global_handler("argilla")
cb = CallbackManager(handlers=[])  # global handler is merged automatically

Defensive patterns

Strategy: validation

Validate before calling

from llama_index.core import global_handler
if global_handler is not None:
    handler_types = {type(h) for h in my_handlers}
    if type(global_handler) in handler_types:
        my_handlers = [h for h in my_handlers if type(h) is not type(global_handler)]
cb = CallbackManager(handlers=my_handlers)

Try / catch

try:
    cb = CallbackManager(handlers=my_handlers)
except ValueError as e:
    if "same type" in str(e):
        my_handlers = [h for h in my_handlers if type(h) is not type(global_handler)]
        cb = CallbackManager(handlers=my_handlers)
    else:
        raise

Prevention

Choose one instrumentation mechanism: global handler OR explicit handlers, not both.
Guard observability setup against double initialization on reloads.

When it happens

Trigger: Setting a global handler (e.g. ArgillaInstrumentor or any BaseCallbackHandler via set_global_handler) and then constructing CallbackManager(handlers=[SameTypeHandler(...)]); commonly triggered implicitly when any component builds a fresh CallbackManager while a global handler is active.

Common situations: Enabling observability globally (set_global_handler) in a notebook/app that also passes its own handler instance into LlamaIndex constructors; upgrading to a version where global-handler merging became strict; initializing the same instrumentor twice (startup + config reload).

Related errors

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