langchain-ai/deepagents · error · ValueError

Invalid agent name: {agent_name!r}. Agent names can only con

Error message

Invalid agent name: {agent_name!r}. Agent names can only contain letters, numbers, hyphens, underscores, and spaces.

What it means

_validate_agent_name enforces that agent profile names match [a-zA-Z0-9_-\s]+ before they are used to build a profile directory path. Names with path separators, dots, or other characters are rejected with ValueError to prevent path traversal and unsafe directory names. get_agent_dir calls this on every agent directory lookup.

Source

Thrown at libs/code/deepagents_code/_paths.py:262

    return PATHS.profile.root


def _validate_agent_name(agent_name: str) -> None:
    """Raise when an agent name cannot safely identify a profile directory.

    Raises:
        ValueError: If the name is empty, unsafe, or reserved by dcode.
    """
    if (
        not agent_name
        or not agent_name.strip()
        or not re.fullmatch(r"[a-zA-Z0-9_\-\s]+", agent_name)
    ):
        msg = (
            f"Invalid agent name: {agent_name!r}. Agent names can only "
            "contain letters, numbers, hyphens, underscores, and spaces."
        )
        raise ValueError(msg)
    from deepagents_code._reserved_names import is_reserved_agent_dir_name

    if is_reserved_agent_dir_name(agent_name):
        msg = f"Invalid agent name: {agent_name!r} is reserved for dcode's own state."
        raise ValueError(msg)


def get_agent_dir(agent_name: str) -> Path:
    """Return the validated profile directory for an agent name.

    Args:
        agent_name: Agent profile name.

    Returns:
        Path to the agent's profile directory.

    """
    _validate_agent_name(agent_name)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Sanitize the agent name before calling: strip/reject characters outside [A-Za-z0-9_- ].
2. Trim whitespace and ensure the name is non-empty.
3. Map or slugify external identifiers (e.g. replace '/' with '-') before use.

Example fix

// before
get_agent_dir(user_input)  // e.g. 'my/agent'
// after
import re
name = re.sub(r"[^a-zA-Z0-9_\- ]", "-", user_input.strip())
get_agent_dir(name)

import re
VALID = re.compile(r"[a-zA-Z0-9_\-\s]+")
def valid_agent_name(name: str) -> bool:
    return bool(name) and bool(VALID.fullmatch(name))

def is_safe_name(name: str) -> bool:
    return bool(name) and re.fullmatch(r"[a-zA-Z0-9_\-\s]+", name) is not None

try:
    agent_dir = get_agent_dir(name)
except ValueError as exc:
    log.error('bad agent name %r: %s', name, exc)
    raise SystemExit(2) from exc

When it happens

Trigger: Calling get_agent_dir(name) (directly or via agent APIs) with a name that is empty, contains '/', '\', '..', or characters outside letters/digits/hyphens/underscores/spaces.

Common situations: Passing a user-supplied agent name straight from config or CLI without sanitizing; deriving the name from a filename that includes an extension; whitespace-only or empty string names.

Related errors

• Invalid MCP server name {server_name!r}: token storage names
• Error: {path_error}
• Path traversal not allowed: {path}
• Windows absolute paths are not supported: {path}. Please use
• Path traversal detected after normalization: {path} -> {norm

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