langchain-ai/deepagents · error · ValueError

`{field_name}` entries must be plain middleware names; class

Error message

`{field_name}` entries must be plain middleware names; class-path (`module:Class`) entries are not currently supported, got {entry!r}.

What it means

Middleware exclusion entries must be plain middleware names; dotted or colon-separated class-path style entries like `module:Class` or `module.Class` are rejected because the registry resolves exclusions by simple public name only. The library intentionally does not support importing arbitrary class paths from config.

Source

Thrown at libs/deepagents/deepagents/profiles/harness/harness_profiles.py:904

    Args:
        entry: Candidate entry. Must be a string to pass.
        field_name: Field being validated, used for error messages.

    Raises:
        TypeError: If `entry` is not a string.
        ValueError: If `entry` violates any of the grammar rules above.
    """
    if not isinstance(entry, str):
        msg = f"`{field_name}` entries must be strings, got {type(entry).__name__} ({entry!r})"
        raise TypeError(msg)
    if not entry or entry.isspace():
        msg = f"`{field_name}` entries must be non-empty, non-whitespace strings"
        raise ValueError(msg)
    if ":" in entry:
        msg = (
            f"`{field_name}` entries must be plain middleware names; class-path (`module:Class`) entries are not currently supported, got {entry!r}."
        )
        raise ValueError(msg)
    if entry.startswith("_"):
        msg = (
            f"`{field_name}` entry {entry!r} cannot start with '_' "
            f"(underscore-prefixed names refer to private middleware classes "
            f"not part of the public exclusion surface)."
        )
        raise ValueError(msg)


def _serialize_runtime_excluded_middleware_entry(
    entry: type[AgentMiddleware] | str,
) -> str:
    """Serialize a runtime `excluded_middleware` entry back to config form.

    Class entries are only serializable when the class advertises a public
    `serialized_name` alias; arbitrary class-path serialization is not
    currently supported.
    """

View on GitHub (pinned to a1af029e6e)

Solutions

Replace the class-path entry with the plain middleware name, e.g. `"summarization"`
Check the harness profile docs/registry for the list of valid public middleware names
If the middleware lacks a public name, exclude it programmatically by class (`.name`) rather than via serialized config

Example fix

# before
config = HarnessProfileConfig(excluded_middleware=["deepagents.middleware.summarization:SummarizationMiddleware"])
# after
config = HarnessProfileConfig(excluded_middleware=["summarization"])

Defensive patterns

Strategy: validation

Validate before calling

if ":" in entry or "." in entry:
    raise ValueError(f"use plain middleware name, not class-path: {entry!r}")

Type guard

def is_plain_middleware_name(entry: str) -> bool:
    return bool(entry) and ":" not in entry and "." not in entry

Try / catch

try:
    config = HarnessProfileConfig(excluded_middleware=entries)
except ValueError as e:
    if "class-path" in str(e):
        entries = [e.split(":")[-1].split(".")[-1].lower() for e in entries]  # then verify against registry
        config = HarnessProfileConfig(excluded_middleware=entries)
    else:
        raise

Prevention

Use only simple lowercase names from the profile registry docs
Reject `module:Class` strings at config-load time
Add a config lint that flags `:` and `.` in middleware names

When it happens

Trigger: Passing e.g. `excluded_middleware=["deepagents.middlewares.summarization:SummarizationMiddleware"]` or any entry containing `:` when building a HarnessProfileConfig or loading a profile config from YAML/JSON.

Common situations: Copying a Python import path or logging-style `module:Class` specifier into the config file; assuming config accepts the same syntax as `entry_points`; migrating configs from another framework that uses class-path references.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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