langchain-ai/deepagents · error · ValueError

Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown fil

Error message

Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown filesystem tool name(s) {unknown!r}; valid names are {sorted(valid_names)}.

What it means

`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.

Source

Thrown at libs/code/deepagents_code/_server_config.py:131

    env_name = f"{SERVER_ENV_PREFIX}ALLOW_FS_TOOLS"
    if env_name not in os.environ:
        return None

    raw = _read_env_json("ALLOW_FS_TOOLS")
    if isinstance(raw, list) and raw and all(isinstance(name, str) for name in raw):
        from typing import get_args

        from deepagents import FsToolName

        valid_names = frozenset(get_args(FsToolName))
        unknown = [name for name in raw if name not in valid_names]
        if unknown:
            msg = (
                f"Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown "
                f"filesystem tool name(s) {unknown!r}; valid names are "
                f"{sorted(valid_names)}."
            )
            raise ValueError(msg)
        return cast("list[FsToolName]", raw)
    msg = (
        f"Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; expected "
        "a non-empty list of filesystem tool names."
    )
    raise ValueError(msg)


def _read_env_str(suffix: str) -> str | None:
    """Read an optional `DEEPAGENTS_CODE_SERVER_*` string variable.

    Args:
        suffix: Variable name suffix after the `DEEPAGENTS_CODE_SERVER_` prefix.

    Returns:
        The string value, or `None` if absent.
    """
    return os.environ.get(f"{SERVER_ENV_PREFIX}{suffix}")

View on GitHub (pinned to a1af029e6e)

Solutions

1. Replace the unknown names with valid ones from the error message: ls, read_file, write_file, edit_file, delete, glob, grep, execute
2. Verify the value is a JSON array of strings, e.g. export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='["read_file","write_file"]'
3. Check the tool names against the installed deepagents-code version (names are pinned in `_constants.FS_TOOL_NAMES` and can change with SDK releases)
4. Use the CLI `--allow-fs-tools` flag instead, which validates with a friendlier error before startup

Example fix

// before
export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='["read_file","writefile"]'
# ValueError: unknown filesystem tool name(s) ['writefile']
// after
export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='["read_file","write_file"]'

import json, os

VALID_FS_TOOLS = {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep", "execute"}
raw = os.environ.get("DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS")
if raw is not None:
    tools = json.loads(raw)
    unknown = [t for t in tools if t not in VALID_FS_TOOLS]
    if unknown:
        raise SystemExit(f"Unknown FS tools {unknown}; valid: {sorted(VALID_FS_TOOLS)}")

def is_valid_fs_tools(raw: object) -> bool:
    return (
        isinstance(raw, list)
        and len(raw) > 0
        and all(isinstance(t, str) and t in VALID_FS_TOOLS for t in raw)
    )

try:
    config = ServerConfig.from_env()
except ValueError as e:
    if "ALLOW_FS_TOOLS" in str(e):
        print(f"Fix DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS: {e}")
        sys.exit(2)
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex
• shell_allow_list must be None or non-empty
• Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'al
• interpreter_ptc list entries cannot include 'all'; use 'all'
• Could not parse embedded resource block. Block expected eith

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/bd0d9e9b6870f4ab. Report an issue: GitHub.