{"record":{"id":"bd0d9e9b6870f4ab","repo":"langchain-ai/deepagents","slug":"invalid-server-env-prefix-allow-fs-tools-value-u","errorCode":null,"errorMessage":"Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown filesystem tool name(s) {unknown!r}; valid names are {sorted(valid_names)}.","messagePattern":"Invalid (.+?)ALLOW_FS_TOOLS value: unknown filesystem tool name\\(s\\) (.+?); valid names are (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_server_config.py","lineNumber":131,"sourceCode":"    env_name = f\"{SERVER_ENV_PREFIX}ALLOW_FS_TOOLS\"\n    if env_name not in os.environ:\n        return None\n\n    raw = _read_env_json(\"ALLOW_FS_TOOLS\")\n    if isinstance(raw, list) and raw and all(isinstance(name, str) for name in raw):\n        from typing import get_args\n\n        from deepagents import FsToolName\n\n        valid_names = frozenset(get_args(FsToolName))\n        unknown = [name for name in raw if name not in valid_names]\n        if unknown:\n            msg = (\n                f\"Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown \"\n                f\"filesystem tool name(s) {unknown!r}; valid names are \"\n                f\"{sorted(valid_names)}.\"\n            )\n            raise ValueError(msg)\n        return cast(\"list[FsToolName]\", raw)\n    msg = (\n        f\"Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; expected \"\n        \"a non-empty list of filesystem tool names.\"\n    )\n    raise ValueError(msg)\n\n\ndef _read_env_str(suffix: str) -> str | None:\n    \"\"\"Read an optional `DEEPAGENTS_CODE_SERVER_*` string variable.\n\n    Args:\n        suffix: Variable name suffix after the `DEEPAGENTS_CODE_SERVER_` prefix.\n\n    Returns:\n        The string value, or `None` if absent.\n    \"\"\"\n    return os.environ.get(f\"{SERVER_ENV_PREFIX}{suffix}\")","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_server_config.py#L113-L149","documentation":"`ServerConfig.from_env()` parses the `DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS` environment variable into a list of filesystem tool names. This `ValueError` is raised when the value is a well-formed JSON list but contains one or more names that are not members of the valid `FsToolName` set (`ls`, `read_file`, `write_file`, `edit_file`, `delete`, `glob`, `grep`, `execute`). The error message names the offending entries and lists all valid names so the fix is self-evident.","triggerScenarios":"Setting `DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS` to a JSON list containing a misspelled, renamed, or nonexistent tool name (e.g. `[\"read_file\", \"write\"]`) and starting the server, so `from_env` -> `_read_env_allow_fs_tools` rejects it at startup.","commonSituations":"Typos in shell profiles / docker env files; copying an allowlist from an older or newer version where a tool was renamed; hand-editing the JSON and inventing a name like `readfile` or `rm`; tooling that generates the env var from an outdated schema.","solutions":["Replace the unknown names with valid ones from the error message: ls, read_file, write_file, edit_file, delete, glob, grep, execute","Verify the value is a JSON array of strings, e.g. export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='[\"read_file\",\"write_file\"]'","Check the tool names against the installed deepagents-code version (names are pinned in `_constants.FS_TOOL_NAMES` and can change with SDK releases)","Use the CLI `--allow-fs-tools` flag instead, which validates with a friendlier error before startup"],"exampleFix":"// before\nexport DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='[\"read_file\",\"writefile\"]'\n# ValueError: unknown filesystem tool name(s) ['writefile']\n// after\nexport DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='[\"read_file\",\"write_file\"]'","handlingStrategy":"validation","validationCode":"import json, os\n\nVALID_FS_TOOLS = {\"ls\", \"read_file\", \"write_file\", \"edit_file\", \"delete\", \"glob\", \"grep\", \"execute\"}\nraw = os.environ.get(\"DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS\")\nif raw is not None:\n    tools = json.loads(raw)\n    unknown = [t for t in tools if t not in VALID_FS_TOOLS]\n    if unknown:\n        raise SystemExit(f\"Unknown FS tools {unknown}; valid: {sorted(VALID_FS_TOOLS)}\")","typeGuard":"def is_valid_fs_tools(raw: object) -> bool:\n    return (\n        isinstance(raw, list)\n        and len(raw) > 0\n        and all(isinstance(t, str) and t in VALID_FS_TOOLS for t in raw)\n    )","tryCatchPattern":"try:\n    config = ServerConfig.from_env()\nexcept ValueError as e:\n    if \"ALLOW_FS_TOOLS\" in str(e):\n        print(f\"Fix DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS: {e}\")\n        sys.exit(2)\n    raise","preventionTips":["Copy tool names only from the error message's valid-names list or FS_TOOL_NAMES","Keep the env var in a checked-in .env template with the exact JSON array format","Prefer the --allow-fs-tools CLI flag over hand-written JSON env values","Re-validate the allowlist after upgrading deepagents-code, since tool names track SDK releases"],"tags":["configuration","env-var","validation","valueerror"],"backgroundTag":"invalid-env-var-value","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}