{"record":{"id":"c40312d4e3548c0c","repo":"langchain-ai/deepagents","slug":"invalid-agent-name-agent-name-r-agent-names-ca","errorCode":null,"errorMessage":"Invalid agent name: {agent_name!r}. Agent names can only contain letters, numbers, hyphens, underscores, and spaces.","messagePattern":"Invalid agent name: (.+?)\\. Agent names can only contain letters, numbers, hyphens, underscores, and spaces\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_paths.py","lineNumber":262,"sourceCode":"    return PATHS.profile.root\n\n\ndef _validate_agent_name(agent_name: str) -> None:\n    \"\"\"Raise when an agent name cannot safely identify a profile directory.\n\n    Raises:\n        ValueError: If the name is empty, unsafe, or reserved by dcode.\n    \"\"\"\n    if (\n        not agent_name\n        or not agent_name.strip()\n        or not re.fullmatch(r\"[a-zA-Z0-9_\\-\\s]+\", agent_name)\n    ):\n        msg = (\n            f\"Invalid agent name: {agent_name!r}. Agent names can only \"\n            \"contain letters, numbers, hyphens, underscores, and spaces.\"\n        )\n        raise ValueError(msg)\n    from deepagents_code._reserved_names import is_reserved_agent_dir_name\n\n    if is_reserved_agent_dir_name(agent_name):\n        msg = f\"Invalid agent name: {agent_name!r} is reserved for dcode's own state.\"\n        raise ValueError(msg)\n\n\ndef get_agent_dir(agent_name: str) -> Path:\n    \"\"\"Return the validated profile directory for an agent name.\n\n    Args:\n        agent_name: Agent profile name.\n\n    Returns:\n        Path to the agent's profile directory.\n\n    \"\"\"\n    _validate_agent_name(agent_name)","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_paths.py#L244-L280","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Sanitize the agent name before calling: strip/reject characters outside [A-Za-z0-9_- ].","Trim whitespace and ensure the name is non-empty.","Map or slugify external identifiers (e.g. replace '/' with '-') before use."],"exampleFix":"// before\nget_agent_dir(user_input)  // e.g. 'my/agent'\n// after\nimport re\nname = re.sub(r\"[^a-zA-Z0-9_\\- ]\", \"-\", user_input.strip())\nget_agent_dir(name)","handlingStrategy":"validation","validationCode":"import re\nVALID = re.compile(r\"[a-zA-Z0-9_\\-\\s]+\")\ndef valid_agent_name(name: str) -> bool:\n    return bool(name) and bool(VALID.fullmatch(name))","typeGuard":"def is_safe_name(name: str) -> bool:\n    return bool(name) and re.fullmatch(r\"[a-zA-Z0-9_\\-\\s]+\", name) is not None","tryCatchPattern":"try:\n    agent_dir = get_agent_dir(name)\nexcept ValueError as exc:\n    log.error('bad agent name %r: %s', name, exc)\n    raise SystemExit(2) from exc","preventionTips":["Sanitize or slugify user-supplied names before creating agents.","Reject or escape path separators at the config-ingestion boundary.","Add a preflight validation step in CLI/config loaders."],"tags":["validation","input-validation","path-traversal"],"backgroundTag":"invalid-identifier-format","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}