langchain-ai/deepagents · error · ValueError

HarnessProfile.excluded_middleware entries matched no middle

Error message

HarnessProfile.excluded_middleware entries matched no middleware across any assembled stack: {', '.join(labels)}. Typo or stale profile — every exclusion must correspond to a middleware actually present at runtime. (Tip: use class-form exclusion when the class is available to catch typos at import time.)

What it means

`create_deep_agent` verifies that every entry in `HarnessProfile.excluded_middleware` actually matched a middleware in the assembled runtime stacks. If one or more entries matched nothing anywhere, `_verify_excluded_middleware_coverage` raises `ValueError` naming the unmatched entries, since a no-op exclusion almost always indicates a typo or a stale profile referencing middleware that no longer exists.

Source

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

            excluded_names.add(entry)

    unmatched_classes = excluded_classes - matched_classes - required_classes
    unmatched_names = excluded_names - matched_names - required_names
    # Private-prefix names are rejected by the config guard; skip them here
    # so the coverage error stays focused on legitimate "didn't match" cases.
    unmatched_names = {name for name in unmatched_names if not name.startswith("_")}
    if not unmatched_classes and not unmatched_names:
        return

    labels = sorted({cls.__name__ for cls in unmatched_classes} | {f"{name!r} (string)" for name in unmatched_names})
    msg = (
        f"HarnessProfile.excluded_middleware entries matched no middleware "
        f"across any assembled stack: {', '.join(labels)}. Typo or stale "
        f"profile — every exclusion must correspond to a middleware actually "
        f"present at runtime. (Tip: use class-form exclusion when the class "
        f"is available to catch typos at import time.)"
    )
    raise ValueError(msg)

View on GitHub (pinned to a1af029e6e)

Solutions

Remove or correct the unmatched entry in `excluded_middleware` (fix the typo or delete the stale name).
Prefer class-form exclusions so typos are caught at import time (`NameError` instead of runtime `ValueError`).
Check the installed library version and update the profile to the current middleware names.

Example fix

// before
HarnessProfile(excluded_middleware=["SumarizationMiddleware"])  # typo
// after
from deepagents import SummarizationMiddleware
HarnessProfile(excluded_middleware=[SummarizationMiddleware])

Defensive patterns

Strategy: validation

Validate before calling

available = {cls.__name__ for stack in stacks for cls in stack_middleware_classes(stack)}
unmatched = [m for m in profile.excluded_middleware if name_of(m) not in available]
if unmatched:
    raise ValueError(f"exclusions match nothing: {unmatched}")

Try / catch

try:
    agent = create_deep_agent(profile=profile, ...)
except ValueError as e:
    if "matched no middleware" in str(e):
        profile = prune_stale_exclusions(profile)
        agent = create_deep_agent(profile=profile, ...)
    else:
        raise

Prevention

Use class-form exclusions so typos fail at import time.
After upgrading the library, diff profile exclusions against current middleware names.
Derive exclusions from an explicit list of imported classes, not hand-typed strings.

When it happens

Trigger: Passing a `HarnessProfile` whose `excluded_middleware` contains a class not included in any stack, or a string name matching no middleware class present at runtime (typo, renamed class, middleware removed in a newer version).

Common situations: Upgrading the library where a middleware was renamed/removed while the profile still lists the old name; misspelling a string exclusion; excluding middleware that is conditionally not assembled for the chosen configuration.

Related errors

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