langchain-ai/deepagents · error · ValueError

interpreter_ptc must be False, 'safe', 'all', or a list of t

Error message

interpreter_ptc must be False, 'safe', 'all', or a list of tool names; got {type(ptc).__name__}.

What it means

interpreter_ptc accepts only False, the strings 'safe'/'all', or a list of tool names. Any other type (int, True, dict, tuple, None, a Tool object) reaches the fallthrough and raises this ValueError naming the offending type. It is the type-level guard at the end of _resolve_ptc_option.

Source

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

            _add(name)

        # Explicit names are passed through unvalidated: the middleware resolves
        # them against the live runtime registry (which includes the SDK
        # built-ins absent from `tools`) and drops any that match nothing.
        absent = sorted(n for n in resolved if n not in live_set)
        if absent:
            logger.debug(
                "interpreter_ptc names not in the build-time toolset (resolved "
                "at runtime if present): %s",
                absent,
            )
        return resolved

    msg = (
        "interpreter_ptc must be False, 'safe', 'all', or a list of tool names; "
        f"got {type(ptc).__name__}."
    )
    raise ValueError(msg)


def _resolve_shell_allow_list() -> list[str] | None:
    """Resolve the shell allow-list for a direct agent-construction caller.

    Returns:
        The configured allow-list, or `None` when shell access is disabled.

    Raises:
        RuntimeError: If the option is absent from the manifest.
    """
    from deepagents_code.config_manifest import _emit_ranked_diagnostics, get_option
    from deepagents_code.configuration.resolver import get_config_resolver

    option = get_option("shell.allow_list")
    if option is None:
        msg = "shell.allow_list is missing from the configuration manifest"
        raise RuntimeError(msg)

View on GitHub (pinned to a1af029e6e)

Solutions

Disable PTC with the boolean False (not None, not 0-dependent truthiness): interpreter_ptc=False.
Use "safe" or "all" as strings, or a real list of tool names.
Coerce/validate the value where it is loaded from config before passing it to create_cli_agent.

Example fix

// before
ptc = config.get("interpreter_ptc")  # None when unset
create_cli_agent(interpreter_ptc=ptc)
// after
ptc = config.get("interpreter_ptc", False)
if isinstance(ptc, tuple):
    ptc = list(ptc)
create_cli_agent(interpreter_ptc=ptc)

Defensive patterns

Strategy: type-guard

Validate before calling

def coerce_ptc(v: object) -> bool | str | list[str]:
    if v is None:
        return False
    if isinstance(v, tuple):
        return list(v)
    if v is False or (isinstance(v, str) and v.strip().lower() in {"safe", "all"}):
        return v
    if isinstance(v, list) and all(isinstance(n, str) for n in v):
        return v
    raise TypeError(f"unsupported interpreter_ptc value: {v!r}")

Type guard

from typing import TypeGuard

def is_valid_ptc(v: object) -> TypeGuard[bool | str | list[str]]:
    if isinstance(v, bool):
        return v is False
    if isinstance(v, str):
        return v.strip().lower() in {"safe", "all"}
    return isinstance(v, list) and all(isinstance(n, str) for n in v)

Try / catch

try:
    agent = create_cli_agent(interpreter_ptc=ptc)
except ValueError as exc:
    logger.error("interpreter_ptc type rejected (%s); defaulting to False", exc)
    agent = create_cli_agent(interpreter_ptc=False)

Prevention

Never pass None or True; disable PTC with the literal False.
Convert config tuples/sets to list[str] before passing.
Annotate the variable as bool | str | list[str] so type checkers catch bad assignments.

When it happens

Trigger: create_cli_agent(interpreter_ptc=True), interpreter_ptc=1, interpreter_ptc=None, interpreter_ptc=("execute",), interpreter_ptc={"tools": [...]}, or a non-str/non-list value read from a YAML/JSON config where the type was not coerced.

Common situations: YAML parsing interpreter_ptc: yes as True; JSON config with null; passing a tuple instead of a list; wiring a config parser's default (None) straight through instead of False.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

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