langchain-ai/deepagents · error · ValueError

Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex

Error message

Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; expected a non-empty list of filesystem tool names.

What it means

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

Source

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

        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}")


def _read_env_int(suffix: str, *, default: int | None) -> int | None:
    """Read a `DEEPAGENTS_CODE_SERVER_*` integer from the environment.

    Args:

View on GitHub (pinned to a1af029e6e)

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

Example fix

// before
export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='read_file,write_file'
# ValueError: expected a non-empty list of filesystem tool names
// after
export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='["read_file","write_file"]'

Defensive patterns

Strategy: validation

Validate before calling

import json, os

raw = os.environ.get("DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS")
if raw is not None:
    value = json.loads(raw)  # raises on malformed JSON
    if not isinstance(value, list) or not value or not all(isinstance(t, str) for t in value):
        raise SystemExit("DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS must be a non-empty JSON array of strings")

Type guard

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

Try / catch

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

Prevention

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

When it happens

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

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

Related errors

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