{"record":{"id":"cfba3e3b8da9abe6","repo":"langchain-ai/deepagents","slug":"invalid-server-env-prefix-allow-fs-tools-value","errorCode":null,"errorMessage":"Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; expected a non-empty list of filesystem tool names.","messagePattern":"Invalid (.+?)ALLOW_FS_TOOLS value: (.+?); expected a non-empty list of filesystem tool names\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_server_config.py","lineNumber":137,"sourceCode":"        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}\")\n\n\ndef _read_env_int(suffix: str, *, default: int | None) -> int | None:\n    \"\"\"Read a `DEEPAGENTS_CODE_SERVER_*` integer from the environment.\n\n    Args:","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_server_config.py#L119-L155","documentation":"`ServerConfig.from_env()` requires `DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS` to parse into a non-empty JSON list of filesystem tool names. This `ValueError` is raised when the value is present but is not parseable as a non-empty list — malformed JSON, a bare string, an empty array `[]`, or a non-list JSON value.","triggerScenarios":"Setting `DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS` to values like `read_file` (bare string, not JSON), `[]`, `[read_file]` (unquoted, invalid JSON), `\"read_file\"` (JSON string not list), or `null`, then calling `from_env` at server startup.","commonSituations":"Forgetting quotes so the shell mangles brackets; writing the variable as a comma-separated string (`read_file,write_file`) instead of a JSON array; leaving an empty array after removing all tools; a deploy template interpolating an empty value.","solutions":["Format the value as a non-empty JSON array of strings: export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='[\"read_file\",\"write_file\"]'","If you want unrestricted filesystem tools, unset the variable entirely rather than setting it to an empty or dummy value","Validate the JSON with python -c \"import json,sys; assert json.loads(sys.argv[1])\" \"$VALUE\" before deploying","Prefer the `--allow-fs-tools` CLI flag, which accepts comma-separated names and gives a friendlier error"],"exampleFix":"// before\nexport DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='read_file,write_file'\n# ValueError: expected a non-empty list of filesystem tool names\n// after\nexport DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='[\"read_file\",\"write_file\"]'","handlingStrategy":"validation","validationCode":"import json, os\n\nraw = os.environ.get(\"DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS\")\nif raw is not None:\n    value = json.loads(raw)  # raises on malformed JSON\n    if not isinstance(value, list) or not value or not all(isinstance(t, str) for t in value):\n        raise SystemExit(\"DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS must be a non-empty JSON array of strings\")","typeGuard":"def is_non_empty_str_list(value: object) -> bool:\n    return isinstance(value, list) and len(value) > 0 and all(isinstance(t, str) for t in value)","tryCatchPattern":"try:\n    config = ServerConfig.from_env()\nexcept ValueError as e:\n    if \"ALLOW_FS_TOOLS\" in str(e):\n        print(f\"Bad DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS value: {e}\")\n        sys.exit(2)\n    raise","preventionTips":["Always single-quote the value in shell so brackets survive: '[\"read_file\"]'","Never set the variable to an empty array; unset it for unrestricted tools","Validate the JSON parses before deploying (python -c \"import json; json.loads(...)\" )","Store the setting in a config file consumed by a JSON-aware loader instead of shell string handling"],"tags":["configuration","env-var","json","validation"],"backgroundTag":"invalid-env-var-value","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}