{"record":{"id":"b0e575e239cbc602","repo":"bytedance/deer-flow","slug":"invalid-agent-name-name-must-match-a-za-z0","errorCode":null,"errorMessage":"Invalid agent name '{name}'. Must match ^[A-Za-z0-9-]+$ (letters, digits, and hyphens only).","messagePattern":"Invalid agent name '(.+?)'\\. Must match \\^\\[A-Za-z0-9-\\]\\+\\$ \\(letters, digits, and hyphens only\\)\\.","errorType":"http","errorClass":"HTTPException","httpStatus":422,"severity":"error","filePath":"backend/app/gateway/routers/agents.py","lineNumber":95,"sourceCode":"    tool_groups: list[str] | None = Field(default=None, description=\"Updated tool group whitelist\")\n    skills: list[str] | None = Field(default=None, description=\"Updated skill whitelist (None=all, []=none)\")\n    model_settings: AgentModelSettings | None = Field(default=None, description=\"Updated per-agent sampling overrides\")\n    thinking_enabled: bool | None = Field(default=None, description=\"Updated per-agent thinking-mode default\")\n    reasoning_effort: ReasoningEffort | None = Field(default=None, description=\"Updated per-agent reasoning-effort default\")\n    soul: str | None = Field(default=None, description=\"Updated SOUL.md content\")\n\n\ndef _validate_agent_name(name: str) -> None:\n    \"\"\"Validate agent name against allowed pattern.\n\n    Args:\n        name: The agent name to validate.\n\n    Raises:\n        HTTPException: 422 if the name is invalid.\n    \"\"\"\n    if not AGENT_NAME_PATTERN.match(name):\n        raise HTTPException(\n            status_code=422,\n            detail=f\"Invalid agent name '{name}'. Must match ^[A-Za-z0-9-]+$ (letters, digits, and hyphens only).\",\n        )\n\n\ndef _normalize_agent_name(name: str) -> str:\n    \"\"\"Normalize agent name to lowercase for filesystem storage.\"\"\"\n    return name.lower()\n\n\ndef _require_agents_api_enabled() -> None:\n    \"\"\"Reject access unless the custom-agent management API is explicitly enabled.\"\"\"\n    if not get_agents_api_config().enabled:\n        raise HTTPException(\n            status_code=403,\n            detail=(\"Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP.\"),\n        )\n","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/agents.py#L77-L113","documentation":"422 from `_validate_agent_name`: the `{name}` path/body parameter does not match `^[A-Za-z0-9-]+$`. Agent names become filesystem directory names (lowercased via `_normalize_agent_name`), so anything besides letters, digits, and hyphens — underscores, spaces, dots, unicode — is rejected up front.","triggerScenarios":"POST/PUT/GET/DELETE `/agents/{name}` with names like `my_agent`, `helper.v2`, `My Agent`, or a slug containing `/`; creating an agent whose display name is passed unslugified.","commonSituations":"Frontends letting users type free-form names and passing them straight through; auto-generating names from emails (`user@x.com`) or titles without slugification; assuming underscore is allowed because it usually is in other slug systems.","solutions":["Slugify the name before the call: lowercase, replace whitespace/underscores with hyphens, strip non `[A-Za-z0-9-]` characters","Run the same regex client-side and block submission early with a helpful message","Use `/agents/check` to validate availability and format before creating"],"exampleFix":"// before\nawait api.createAgent({ name: 'My Cool Agent' }); // 422\n// after\nconst name = 'My Cool Agent'.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');\nawait api.createAgent({ name }); // 'my-cool-agent'","handlingStrategy":"validation","validationCode":"import re\nAGENT_NAME_RE = re.compile(r'^[A-Za-z0-9-]+$')\nif not AGENT_NAME_RE.fullmatch(name):\n    raise ValueError(f'invalid agent name: {name!r}')","typeGuard":"const isValidAgentName = (n: string): boolean => /^[A-Za-z0-9-]+$/.test(n);","tryCatchPattern":"try { await api.createAgent(body); }\ncatch (e) {\n  if (e.status === 422 && /agent name/i.test(e.detail)) { showNameError(slugify(name)); return; }\n  throw e;\n}","preventionTips":["Slugify free-text names client-side before any agents API call","Reuse the exact regex ^[A-Za-z0-9-]+$ in frontend validation","Remember names are normalized to lowercase — compare case-insensitively for uniqueness"],"tags":["validation","http-422","agents","slug"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}