langchain-ai/langchain · error · ValueError

The dispatcher API does not accept additional keyword argume

Error message

The dispatcher API does not accept additional keyword arguments.Please do not pass any additional keyword arguments, instead include them in the data field.

What it means

`CallbackManager.on_custom_event` (manager.py) raises `ValueError` when callers pass extra `**kwargs`. The dispatcher API deliberately accepts only `name` and `data`; arbitrary keyword arguments are rejected so event payloads stay serializable and handler signatures stay stable. Put everything in the `data` dict instead.

Source

Thrown at libs/core/langchain_core/callbacks/manager.py:1667

        tailored to their application.

        Args:
            name: The name of the adhoc event.
            data: The data for the adhoc event.
            run_id: The ID of the run.

        Raises:
            ValueError: If additional keyword arguments are passed.
        """
        if not self.handlers:
            return
        if kwargs:
            msg = (
                "The dispatcher API does not accept additional keyword arguments."
                "Please do not pass any additional keyword arguments, instead "
                "include them in the data field."
            )
            raise ValueError(msg)
        if run_id is None:
            run_id = uuid7()

        handle_event(
            self.handlers,
            "on_custom_event",
            "ignore_custom_event",
            name,
            data,
            run_id=run_id,
            tags=self.tags,
            metadata=self.metadata,
        )

    @classmethod
    def configure(
        cls,
        inheritable_callbacks: Callbacks = None,

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Move every extra keyword into the `data` dict: `on_custom_event('evt', {'foo': 'bar', ...})`
2. If you meant to set the run id, pass it positionally/dedicated parameter or dispatch from within a run via `dispatch_custom_event`
3. Audit call sites for `**` unpacking into the dispatcher call
4. Add a lint/test that asserts dispatcher calls use only (name, data)

Example fix

# before
manager.on_custom_event("tool_feedback", result, user_id="42")

# after
manager.on_custom_event("tool_feedback", {"result": result, "user_id": "42"})

def dispatch(manager, name: str, data: dict) -> None:
    # enforce (name, data)-only contract before the manager does
    manager.on_custom_event(name, data)

# lint-level guard: reject call sites with extra kwargs
def _no_kwargs(**kw):
    if kw:
        raise TypeError('use data= for payloads')

When it happens

Trigger: Calling `callback_manager.on_custom_event('my_event', payload, foo='bar')` (sync variant) — any non-empty kwargs dict triggers it; copying a call from user code to `adispatch_custom_event` while keeping kwargs; older snippets that passed `run_id=` or metadata as kwargs.

Common situations: Adapting pre-1.0 examples that spread kwargs into the event call; trying to attach run_id/tags per-call (must go through config or `data`); IDE autocompletion suggesting arbitrary kwargs because the signature has `**kwargs` only to raise on it.

Related errors

• Unable to dispatch an adhoc event without a parent run id.Th
• tags must be a list of the same length as prompts
• Exactly one argument in each of the following groups must be
• invalid IP address
• Failed to resolve hostname '{hostname}': {e}

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/b938d83b36b2c755. Report an issue: GitHub.