What causes "callbacks must be the same length as prompts" in langchain-ai/langchain?

For one handler set across all prompts, pass it flat: `callbacks=handler` or `callbacks=[handler]` where the handler is not itself a list.

langchain-ai/langchain · error · ValueError

callbacks must be the same length as prompts

Error message

callbacks must be the same length as prompts

What it means

`ValueError` from `BaseLLM.generate`: per-input callbacks were supplied as a list of callback args (a list whose first element is itself a list, a `BaseCallbackManager`, or `None`), which switches the API into per-prompt mode — and that list's length must equal `len(prompts)`. A mismatch means some prompts would silently get no handlers.

Source

Thrown at libs/core/langchain_core/language_models/llms.py:939

                for meta in metadata
            ]
        elif isinstance(metadata, dict):
            metadata = {
                **(metadata or {}),
                **self._get_ls_params_with_defaults(stop=stop, **kwargs),
            }
        if (
            isinstance(callbacks, list)
            and callbacks
            and (
                isinstance(callbacks[0], (list, BaseCallbackManager))
                or callbacks[0] is None
            )
        ):
            # We've received a list of callbacks args to apply to each input
            if len(callbacks) != len(prompts):
                msg = "callbacks must be the same length as prompts"
                raise ValueError(msg)
            if tags is not None and not (
                isinstance(tags, list) and len(tags) == len(prompts)
            ):
                msg = "tags must be a list of the same length as prompts"
                raise ValueError(msg)
            if metadata is not None and not (
                isinstance(metadata, list) and len(metadata) == len(prompts)
            ):
                msg = "metadata must be a list of the same length as prompts"
                raise ValueError(msg)
            if run_name is not None and not (
                isinstance(run_name, list) and len(run_name) == len(prompts)
            ):
                msg = "run_name must be a list of the same length as prompts"
                raise ValueError(msg)
            tags_list = cast("list[list[str] | None]", tags or ([None] * len(prompts)))
            metadata_list = cast(
                "list[builtins.dict[str, Any] | None]",

View on GitHub (pinned to e32fa9a52e)

Solutions

For one handler set across all prompts, pass it flat: `callbacks=handler` or `callbacks=[handler]` where the handler is not itself a list.
For per-prompt callbacks, build exactly one entry per prompt: `[handlers[i] for i in range(len(prompts))]`.
Zip-derive both from the same source list so they cannot diverge.
Validate lengths before the call in your own wrapper.

Example fix

# before
llm.generate([p1, p2, p3], callbacks=[[cb1], [cb2]])  # 3 prompts, 2 entries

# after
llm.generate([p1, p2, p3], callbacks=[[cb1], [cb2], [cb3]])
# or, same handlers for all:
llm.generate([p1, p2, p3], callbacks=cb1)

Defensive patterns

Strategy: validation

Validate before calling

per_prompt = (
    isinstance(callbacks, list)
    and callbacks
    and (isinstance(callbacks[0], (list, BaseCallbackManager)) or callbacks[0] is None)
)
if per_prompt and len(callbacks) != len(prompts):
    callbacks = callbacks + [None] * (len(prompts) - len(callbacks))  # or raise

Type guard

from langchain_core.callbacks import BaseCallbackManager
def is_per_prompt_callbacks(callbacks: object) -> bool:
    return (
        isinstance(callbacks, list)
        and bool(callbacks)
        and (isinstance(callbacks[0], (list, BaseCallbackManager)) or callbacks[0] is None)
    )

Try / catch

try:
    result = llm.generate(prompts, callbacks=callbacks)
except ValueError as e:
    if "same length as prompts" in str(e):
        raise ValueError(f"align callbacks ({len(callbacks)}) with prompts ({len(prompts)})") from e
    raise

Prevention

Pass a single flat handler (not nested) when all prompts share handlers.
Build per-prompt callback lists with a comprehension over the prompts list itself.
Validate lengths of `callbacks`/`tags`/`metadata`/`run_name` together in wrappers.

When it happens

Trigger: Calling `llm.generate(prompts, callbacks=[handler_a, handler_b])` where `handler_a` is itself a list/manager (or `None`) — interpreted as per-prompt callbacks — with a different count than prompts. E.g. `generate([p1, p2, p3], callbacks=[[cb1], [cb2]])`.

Common situations: Mixing up the two `callbacks` shapes (flat handler list vs. nested per-prompt list); passing `callbacks=[None, handler]` for two of five prompts; dynamically building per-prompt handler lists that drift out of sync with prompt filtering.

Related errors

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