{"record":{"id":"78ea70e400de8648","repo":"langchain-ai/deepagents","slug":"field-name-entries-must-be-plain-middleware-na","errorCode":null,"errorMessage":"`{field_name}` entries must be plain middleware names; class-path (`module:Class`) entries are not currently supported, got {entry!r}.","messagePattern":"`(.+?)` entries must be plain middleware names; class-path \\(`module:Class`\\) entries are not currently supported, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/profiles/harness/harness_profiles.py","lineNumber":904,"sourceCode":"    Args:\n        entry: Candidate entry. Must be a string to pass.\n        field_name: Field being validated, used for error messages.\n\n    Raises:\n        TypeError: If `entry` is not a string.\n        ValueError: If `entry` violates any of the grammar rules above.\n    \"\"\"\n    if not isinstance(entry, str):\n        msg = f\"`{field_name}` entries must be strings, got {type(entry).__name__} ({entry!r})\"\n        raise TypeError(msg)\n    if not entry or entry.isspace():\n        msg = f\"`{field_name}` entries must be non-empty, non-whitespace strings\"\n        raise ValueError(msg)\n    if \":\" in entry:\n        msg = (\n            f\"`{field_name}` entries must be plain middleware names; class-path (`module:Class`) entries are not currently supported, got {entry!r}.\"\n        )\n        raise ValueError(msg)\n    if entry.startswith(\"_\"):\n        msg = (\n            f\"`{field_name}` entry {entry!r} cannot start with '_' \"\n            f\"(underscore-prefixed names refer to private middleware classes \"\n            f\"not part of the public exclusion surface).\"\n        )\n        raise ValueError(msg)\n\n\ndef _serialize_runtime_excluded_middleware_entry(\n    entry: type[AgentMiddleware] | str,\n) -> str:\n    \"\"\"Serialize a runtime `excluded_middleware` entry back to config form.\n\n    Class entries are only serializable when the class advertises a public\n    `serialized_name` alias; arbitrary class-path serialization is not\n    currently supported.\n    \"\"\"","sourceCodeStart":886,"sourceCodeEnd":922,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/profiles/harness/harness_profiles.py#L886-L922","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nconfig = HarnessProfileConfig(excluded_middleware=[\"deepagents.middleware.summarization:SummarizationMiddleware\"])\n# after\nconfig = HarnessProfileConfig(excluded_middleware=[\"summarization\"])","handlingStrategy":"validation","validationCode":"if \":\" in entry or \".\" in entry:\n    raise ValueError(f\"use plain middleware name, not class-path: {entry!r}\")","typeGuard":"def is_plain_middleware_name(entry: str) -> bool:\n    return bool(entry) and \":\" not in entry and \".\" not in entry","tryCatchPattern":"try:\n    config = HarnessProfileConfig(excluded_middleware=entries)\nexcept ValueError as e:\n    if \"class-path\" in str(e):\n        entries = [e.split(\":\")[-1].split(\".\")[-1].lower() for e in entries]  # then verify against registry\n        config = HarnessProfileConfig(excluded_middleware=entries)\n    else:\n        raise","preventionTips":["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"],"tags":["config","validation","middleware","naming"],"backgroundTag":"invalid-config-value","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}