{"record":{"id":"3b80143f615c4c46","repo":"langchain-ai/deepagents","slug":"harnessprofile-excluded-middleware-is-invalid-3b8014","errorCode":null,"errorMessage":"HarnessProfile.excluded_middleware is invalid:\n  - required scaffolding cannot be excluded: {', '.join(labels)} (back filesystem tools, subagent dispatch, and permission enforcement — use excluded_tools for per-tool visibility or adjust profile settings instead of stripping scaffolding)","messagePattern":"HarnessProfile\\.excluded_middleware is invalid:\n  - required scaffolding cannot be excluded: (.+?) \\(back filesystem tools, subagent dispatch, and permission enforcement — use excluded_tools for per-tool visibility or adjust profile settings instead of stripping scaffolding\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/profiles/harness/harness_profiles.py","lineNumber":336,"sourceCode":"    is dropped too. Async subagents are unaffected.\n    \"\"\"\n\n    def __post_init__(self) -> None:\n        \"\"\"Freeze mutable mappings and validate grammar of string entries.\"\"\"\n        if not isinstance(self.tool_description_overrides, MappingProxyType):\n            object.__setattr__(\n                self,\n                \"tool_description_overrides\",\n                MappingProxyType(dict(self.tool_description_overrides)),\n            )\n        scaffolding_violations: list[str] = []\n        for entry in self.excluded_middleware:\n            _validate_config_middleware_string(entry, \"excluded_middleware\")\n            label = _scaffolding_violation_label(entry)\n            if label is not None:\n                scaffolding_violations.append(label)\n        if scaffolding_violations:\n            raise ValueError(_format_scaffolding_rejection(scaffolding_violations))\n\n    def to_dict(self) -> dict[str, Any]:\n        \"\"\"Dump this config to plain dict/list/scalar values.\n\n        Suitable for `json.dumps` or `yaml.safe_dump`. Fields at their\n        default are omitted so the output stays minimal and round-trips\n        cleanly through `from_dict`.\n\n        Returns:\n            A plain dict containing only the fields set on this config.\n\n        Raises:\n            TypeError: If `tool_description_overrides` contains a non-string\n                key or value.\n        \"\"\"\n        out: dict[str, Any] = {}\n        if self.base_system_prompt is not None:\n            out[\"base_system_prompt\"] = self.base_system_prompt","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/profiles/harness/harness_profiles.py#L318-L354","documentation":"HarnessProfileConfig.__post_init__ protects required agent scaffolding. Middleware listed in excluded_middleware that is identified by _scaffolding_violation_label as core (back filesystem tools, subagent dispatch, permission enforcement) triggers ValueError via _format_scaffolding_rejection, because removing it would break deepagents' core invariants. The message directs you to excluded_tools or profile settings instead.","triggerScenarios":"Constructing HarnessProfileConfig(...) with excluded_middleware containing core middleware names (e.g. filesystem-tools, subagents/Summarization-style dispatch, permissions/hitl middleware), whether in code or in a YAML/JSON profile file.","commonSituations":"Profile authors trying to slim the agent by stripping required middleware; copying an old config that excluded middleware now classified as scaffolding after a version change.","solutions":["Remove the core middleware name from excluded_middleware.","Use excluded_tools to hide specific tools instead of excluding whole middleware.","Adjust profile settings (permissions mode, tool visibility) rather than stripping scaffolding.","Check release notes if this config worked in an older deepagents version."],"exampleFix":"// before\nHarnessProfileConfig(name=\"thin\", excluded_middleware=[\"filesystem_tools\"])\n// after\nHarnessProfileConfig(name=\"thin\", excluded_tools=[\"ls\", \"read_file\"])\n","handlingStrategy":"try-catch","validationCode":"SCAFFOLDING = {\"filesystem_tools\", \"subagents\", \"permissions\"}\nbad = [m for m in getattr(cfg, \"excluded_middleware\", []) if m in SCAFFOLDING]\nif bad:\n    raise ValueError(f\"cannot exclude scaffolding: {bad}\")","typeGuard":null,"tryCatchPattern":"try:\n    config = HarnessProfileConfig(**raw)\nexcept ValueError as e:\n    if \"excluded_middleware is invalid\" in str(e):\n        logging.error(\"%s — move to excluded_tools\", e)\n        raw.pop(\"excluded_middleware\", None)\n        config = HarnessProfileConfig(**raw)\n    else:\n        raise","preventionTips":["Use excluded_tools for tool-level hiding instead of middleware exclusion","Never strip filesystem, subagent-dispatch, or permission middleware from profiles","Re-check profile configs after upgrading deepagents (scaffolding set may grow)"],"tags":["python","profiles","middleware","config"],"backgroundTag":"invalid-profile-config","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}