langchain-ai/langchain · error · RuntimeError

Unable to dispatch an adhoc event without a parent run id.Th

Error message

Unable to dispatch an adhoc event without a parent run id.This function can only be called from within an existing run (e.g.,inside a tool or a RunnableLambda or a RunnableGenerator.)If you are doing that and still seeing this error, try explicitlypassing the config parameter to this function.

What it means

`adispatch_custom_event` (manager.py ~2730) needs a parent run to attach the event to; it looks up the current run's callback manager and raises `RuntimeError` when `parent_run_id is None`. Without an active run (or without passing the `config` of the current run), there is no run to parent the event to.

Source

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

        ensure_config,
        get_async_callback_manager_for_config,
    )

    config = ensure_config(config)
    callback_manager = get_async_callback_manager_for_config(config)
    # We want to get the callback manager for the parent run.
    # This is a work-around for now to be able to dispatch adhoc events from
    # within a tool or a lambda and have the metadata events associated
    # with the parent run rather than have a new run id generated for each.
    if callback_manager.parent_run_id is None:
        msg = (
            "Unable to dispatch an adhoc event without a parent run id."
            "This function can only be called from within an existing run (e.g.,"
            "inside a tool or a RunnableLambda or a RunnableGenerator.)"
            "If you are doing that and still seeing this error, try explicitly"
            "passing the config parameter to this function."
        )
        raise RuntimeError(msg)

    await callback_manager.on_custom_event(
        name,
        data,
        run_id=callback_manager.parent_run_id,
    )


def dispatch_custom_event(
    name: str, data: Any, *, config: RunnableConfig | None = None
) -> None:
    """Dispatch an adhoc event.

    Args:
        name: The name of the adhoc event.
        data: The data for the adhoc event.

            Free form data. Ideally should be JSON serializable to avoid serialization

View on GitHub (pinned to e32fa9a52e)

Solutions

  1. Pass the config explicitly: `await adispatch_custom_event(name, data, config=config)` inside the tool/lambda that received it
  2. Only dispatch from within a runnable, tool, RunnableLambda, or RunnableGenerator execution
  3. If outside a run, wrap the logic in a `RunnableLambda` (or start a run via a tracer) so a parent exists
  4. Ensure contextvars propagate into spawned tasks (create tasks from within the run, not before it)

Example fix

# before
async def my_tool(args: dict) -> str:
    await adispatch_custom_event("tool_note", {"stage": "start"})
    ...

# after
async def my_tool(args: dict, config: RunnableConfig) -> str:
    await adispatch_custom_event("tool_note", {"stage": "start"}, config=config)
    ...
Defensive patterns

Strategy: try-catch

Validate before calling

from langchain_core.callbacks import adispatch_custom_event

def has_parent_run(config) -> bool:
    return bool(config and config.get('callbacks'))  # heuristic; prefer structural check

# structural prevention: always pass config from the enclosing runnable

Try / catch

try:
    await adispatch_custom_event(name, data, config=config)
except RuntimeError as e:
    if 'parent run id' in str(e):
        logger.debug('no active run for %s; skipping event', name)
    else:
        raise

Prevention

When it happens

Trigger: Calling `await adispatch_custom_event(...)` outside any runnable execution; calling it inside a tool/lambda but omitting the `config` parameter so the contextvar lookup finds no run; dispatching from a thread the contextvars didn't propagate to.

Common situations: Custom events fired from helper functions that never received `config`; async tools that drop `run_manager`/config; events dispatched in background tasks spawned off the run's task tree; calling the API at module import or in tests without a run context.

Related errors

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