{"record":{"id":"be2385bc9b61e276","repo":"langchain-ai/deepagents","slug":"field-name-entry-entry-r-cannot-start-with","errorCode":null,"errorMessage":"`{field_name}` entry {entry!r} cannot start with '_' (underscore-prefixed names refer to private middleware classes not part of the public exclusion surface).","messagePattern":"`(.+?)` entry (.+?) cannot start with '_' \\(underscore-prefixed names refer to private middleware classes not part of the public exclusion surface\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/profiles/harness/harness_profiles.py","lineNumber":911,"sourceCode":"    \"\"\"\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    \"\"\"\n    if isinstance(entry, str):\n        return entry\n\n    alias = getattr(entry, \"serialized_name\", None)\n    if isinstance(alias, str) and alias:\n        return alias\n","sourceCodeStart":893,"sourceCodeEnd":929,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/profiles/harness/harness_profiles.py#L893-L929","documentation":"Middleware names starting with an underscore are reserved as private and cannot be referenced in config exclusion lists. Underscore-prefixed names map to private middleware classes that are not part of the public exclusion surface, so allowing them would create an unstable API contract.","triggerScenarios":"Passing an entry like `\"_summarization\"` in `excluded_middleware` (or another validated middleware string list) when constructing a HarnessProfileConfig.","commonSituations":"Reading library internals and copying a private class's name into config; assuming underscore names are addressable because they appear in source; typo'd names accidentally prefixed with `_`.","solutions":["Drop the leading underscore or use the corresponding public middleware name","Look up the public alias of the middleware in the profile registry","If you truly need to exclude a private middleware, do it in code via the class object rather than string config"],"exampleFix":"# before\nconfig = HarnessProfileConfig(excluded_middleware=[\"_summarization\"])\n# after\nconfig = HarnessProfileConfig(excluded_middleware=[\"summarization\"])","handlingStrategy":"validation","validationCode":"if any(n.startswith(\"_\") for n in excluded_middleware):\n    raise ValueError(\"private (_-prefixed) middleware names are not excludable\")","typeGuard":"def is_public_middleware_name(entry: str) -> bool:\n    return bool(entry) and not entry.startswith(\"_\") and \":\" not in entry","tryCatchPattern":"try:\n    config = HarnessProfileConfig(excluded_middleware=entries)\nexcept ValueError as e:\n    if \"cannot start with '_'\" in str(e):\n        entries = [n.lstrip(\"_\") for n in entries]\n        config = HarnessProfileConfig(excluded_middleware=entries)\n    else:\n        raise","preventionTips":["Treat underscore-prefixed identifiers as private library internals","Only reference names documented in the public middleware registry","Strip or remap underscore names when importing configs from other sources"],"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"}