{"record":{"id":"ca535a284f06424a","repo":"langchain-ai/deepagents","slug":"argv-0-must-be-a-non-empty-executable-path","errorCode":null,"errorMessage":"argv[0] must be a non-empty executable path.","messagePattern":"argv\\[0\\] must be a non-empty executable path\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/hooks/models/config.py","lineNumber":51,"sourceCode":"\n    type: Literal[\"command\"]\n    command: str\n    argv: list[str] | None = None\n    timeout: float | None = Field(default=None, gt=0, allow_inf_nan=False)\n    status_message: str | None = Field(default=None, alias=\"statusMessage\")\n    async_: bool | None = Field(default=None, alias=\"async\")\n\n    @field_validator(\"argv\", mode=\"after\")\n    @classmethod\n    def _normalize_argv(cls, value: list[str] | None) -> list[str] | None:\n        if value is None:\n            return None\n        if not value or not all(isinstance(part, str) for part in value):\n            msg = \"argv must be a non-empty list of strings when provided.\"\n            raise ValueError(msg)\n        if not value[0].strip():\n            msg = \"argv[0] must be a non-empty executable path.\"\n            raise ValueError(msg)\n        return value\n\n    @field_validator(\"async_\", mode=\"after\")\n    @classmethod\n    def _normalize_async(cls, value: bool | None) -> None:\n        if value:\n            msg = \"async command hooks are not yet supported.\"\n            raise ValueError(msg)\n\n\n# Extension point for future handler kinds, kept as a plain assignment rather\n# than a `type` alias: a `type` alias becomes the schema identity and renames\n# the generated `$defs` entry from `CommandHandlerSpec` to `HandlerSpec`.\nHandlerSpec = CommandHandlerSpec\n\n\nclass MatcherGroup(_ConfigModel):\n    \"\"\"A matcher and its ordered hook handlers.\"\"\"","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/hooks/models/config.py#L33-L69","documentation":"After checking list contents, `_normalize_argv` verifies that the first argv element is a non-blank string, since `argv[0]` is the executable path passed to process spawning. An argv whose first entry is empty or whitespace-only cannot identify a program, so validation fails.","triggerScenarios":"Constructing a `CommandHandlerSpec` with `argv=[\"\", \"--flag\"]`, `argv=[\"  \"]`, or where the executable string was produced from an empty/whitespace env var or unset setting.","commonSituations":"Env-var-driven hook commands (`HOOK_CMD=\"\"`) interpolated into argv[0]; template/config rendering that leaves the command slot blank; copy-paste of hook examples with the binary name removed.","solutions":["Set `argv[0]` to the actual executable path or name (e.g. `\"python\"`, `\"/usr/local/bin/myhook\")`","Check the source of the value (env var, setting, template) and ensure it is populated and trimmed","Use an absolute path if the executable is not on PATH"],"exampleFix":"// before\nCommandHandlerSpec(argv=[os.environ.get(\"HOOK_BIN\", \"\"), \"run\"])\n// after\nhook_bin = os.environ.get(\"HOOK_BIN\", \"/usr/local/bin/myhook\").strip()\nCommandHandlerSpec(argv=[hook_bin, \"run\"])","handlingStrategy":"validation","validationCode":"if argv and (not isinstance(argv[0], str) or not argv[0].strip()):\n    raise ValueError(\"argv[0] must be a non-empty executable path\")","typeGuard":"def has_executable_head(argv: list[str]) -> bool:\n    return bool(argv) and isinstance(argv[0], str) and argv[0].strip() != \"\"","tryCatchPattern":"try:\n    spec = CommandHandlerSpec(argv=argv)\nexcept ValueError as e:\n    logger.error(\"bad hook command: %s\", e)\n    sys.exit(1)","preventionTips":["Resolve the executable from env/settings with a non-empty default and .strip() it","Prefer absolute paths for hook binaries","Validate env-var-derived command fields before interpolation into argv"],"tags":["validation","pydantic","config","hooks"],"backgroundTag":"schema-validation-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}