langchain-ai/deepagents · error · ValueError

Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'al

Error message

Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'all', or a list of tool names.

What it means

_resolve_ptc_option normalizes the interpreter_ptc option into a list of tool names exposed to Python-tool-call (PTC) execution. A string value must be exactly 'safe' or 'all' (after strip/lower); anything else is rejected so an unrecognized sentinel never silently narrows or widens the exposed toolset. This is an eager fail-fast ValueError raised at agent construction time.

Source

Thrown at libs/code/deepagents_code/agent.py:1040

                raise ValueError(msg)
            # `all` can only enumerate the tools passed to `create_cli_agent`;
            # SDK runtime built-ins (filesystem, `task`, …) are injected later
            # and are not enumerable here. Exposing them under `all` needs an
            # "expose everything" sentinel in `CodeInterpreterMiddleware`
            # (tracked in langchain-ai/deepagents#3847).
            included = sorted(live_set)
            write_included = sorted(_INTERPRETER_WRITE_TOOLS & live_set)
            if write_included:
                logger.info(
                    "interpreter_ptc='all' includes write/shell tools: %s",
                    write_included,
                )
            return included
        msg = (
            f"Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'all', "
            "or a list of tool names."
        )
        raise ValueError(msg)

    if isinstance(ptc, list):
        from deepagents_code.config import INTERPRETER_PTC_SAFE_PRESET

        if any(name.strip().lower() == "all" for name in ptc):
            msg = (
                "interpreter_ptc list entries cannot include 'all'; use 'all' "
                "as a standalone value or list explicit tool names (optionally "
                "with the 'safe' preset)."
            )
            raise ValueError(msg)

        resolved: list[str] = []
        seen: set[str] = set()

        def _add(name: str) -> None:
            if name not in seen:
                seen.add(name)

View on GitHub (pinned to a1af029e6e)

Solutions

Use exactly 'safe' for the curated preset or 'all' (with interpreter_ptc_acknowledge_unsafe=True or auto_approve=True) — the check is case-insensitive and whitespace-tolerant, so casing is not the issue.
If you meant one specific tool, pass a list: interpreter_ptc=["execute"].
If you meant to disable PTC, pass interpreter_ptc=False.
Check the configured value in your dcode config file / env mapping for typos or stale values.

Example fix

// before
create_cli_agent(interpreter_ptc="safe-preset")
// after
create_cli_agent(interpreter_ptc="safe")
// or for one tool
create_cli_agent(interpreter_ptc=["execute"])

Defensive patterns

Strategy: validation

Validate before calling

VALID = {"safe", "all"}
if isinstance(ptc, str) and ptc.strip().lower() not in VALID:
    raise ValueError(f"interpreter_ptc must be 'safe' or 'all', got {ptc!r}")

Type guard

def is_valid_ptc_string(v: object) -> TypeGuard[Literal['safe', 'all']]:
    return isinstance(v, str) and v.strip().lower() in {"safe", "all"}

Try / catch

try:
    agent = create_cli_agent(interpreter_ptc=ptc)
except ValueError as exc:
    logger.error("Bad interpreter_ptc value: %s", exc)
    agent = create_cli_agent(interpreter_ptc="safe")

Prevention

Treat interpreter_ptc as an enum: only pass the literals 'safe', 'all', or False.
Pass single tool names as a one-element list, never a bare string.
Centralize the value in one config constant instead of repeating string literals.

When it happens

Trigger: Calling create_cli_agent(interpreter_ptc=<str>) where the string is not 'safe' or 'all' — e.g. interpreter_ptc=' Safe-Mode ', interpreter_ptc='builtin', interpreter_ptc='ALL ' is fine but 'everything', 'none' (use False), or a single tool name passed as a string instead of a list all raise.

Common situations: Config-file value like interpreter_ptc = "safe-preset" or "enabled"; passing a single tool name as a bare string instead of a one-element list; typos like 'safelist' or 'whitelist'; copying an older option value that predates the 'safe'/'all' sentinel vocabulary.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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