langchain-ai/deepagents · error · ValueError

HarnessProfile.excluded_middleware name entry matched multip

Error message

HarnessProfile.excluded_middleware name entry matched multiple distinct middleware classes within a single stack: {'; '.join(labels)}. Use a class-form exclusion via the runtime `HarnessProfile` to disambiguate.

What it means

When applying a `HarnessProfile`, a string entry in `excluded_middleware` matched more than one distinct middleware class within a single assembled stack, making the exclusion ambiguous. `_raise_on_name_collisions` raises `ValueError` and instructs the developer to use a class-form exclusion to disambiguate.

Source

Thrown at libs/deepagents/deepagents/_excluded_middleware.py:87

) -> None:
    """Raise `ValueError` if any string exclusion matched multiple distinct classes.

    A string entry that drops instances of more than one concrete class is
    almost always a surprise — e.g. a user middleware whose `.name`
    accidentally collides with a built-in alias. Force the caller to use a
    class-form exclusion via the runtime `HarnessProfile` to disambiguate.
    """
    collisions = {name: classes for name, classes in name_matched_types.items() if len(classes) > 1}
    if not collisions:
        return
    labels = sorted(f"{name!r} matched {sorted(cls.__name__ for cls in classes)}" for name, classes in collisions.items())
    msg = (
        "HarnessProfile.excluded_middleware name entry matched multiple "
        "distinct middleware classes within a single stack: "
        f"{'; '.join(labels)}. Use a class-form exclusion via the runtime "
        "`HarnessProfile` to disambiguate."
    )
    raise ValueError(msg)


def _apply_excluded_middleware(
    stack: list[AgentMiddleware[Any, Any, Any]],
    profile: HarnessProfile,
    *,
    matched_classes: set[type[AgentMiddleware[Any, Any, Any]]] | None = None,
    matched_names: set[str] | None = None,
) -> list[AgentMiddleware[Any, Any, Any]]:
    """Drop middleware in the stack matched by `profile.excluded_middleware`.

    Class entries match on exact type (not `isinstance`), mirroring the
    slot-identity semantics of `_merge_middleware` so a subclass introduced
    by the caller is preserved when the profile excludes the base class.
    String entries match `AgentMiddleware.name` exactly — defaults to the
    class's `__name__` but is overridable when the public alias differs from
    the impl class (e.g. `SummarizationMiddleware` for
    `_DeepAgentsSummarizationMiddleware`).

View on GitHub (pinned to a1af029e6e)

Solutions

Replace the ambiguous string entry with the explicit middleware class in `excluded_middleware`.
Rename your custom middleware class so it no longer collides with the built-in name.
If both same-named middlewares are intended, scope exclusions per-stack rather than by bare name.

Example fix

// before
HarnessProfile(excluded_middleware=["SummarizationMiddleware"])
// after
from my_stack import MySummarizationMiddleware
HarnessProfile(excluded_middleware=[MySummarizationMiddleware])

Defensive patterns

Strategy: validation

Validate before calling

from collections import Counter
name_counts = Counter(m for m in profile.excluded_middleware if isinstance(m, str))
dupes = [n for n, c in name_counts.items() if c > 1]
if dupes:
    raise ValueError(f"ambiguous string exclusions: {dupes}")

Try / catch

try:
    agent = create_deep_agent(profile=profile, ...)
except ValueError as e:
    if "matched multiple distinct middleware classes" in str(e):
        profile = replace_strings_with_classes(profile)  # class-form exclusions
        agent = create_deep_agent(profile=profile, ...)
    else:
        raise

Prevention

Prefer class-form exclusions over string names to eliminate ambiguity.
Avoid naming custom middleware after built-in middleware classes.
Keep middleware imports centralized so collisions are visible at import time.

When it happens

Trigger: `create_deep_agent`/`_apply_excluded_middleware` assembles stacks where two different middleware classes share a name referenced by a string entry in `profile.excluded_middleware` (e.g. two packages both exporting a class with the same short name, or the same name registered on multiple stacks).

Common situations: Using string names in profiles when multiple middleware providers define same-named classes; custom middleware named identically to a built-in; combining partner packages that both ship e.g. a `SummarizationMiddleware`.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/06a768f2b59e7438. Report an issue: GitHub.