bytedance/deer-flow · error · HTTPException

Invalid agent name '{name}'. Must match ^[A-Za-z0-9-]+$ (let

Error message

Invalid agent name '{name}'. Must match ^[A-Za-z0-9-]+$ (letters, digits, and hyphens only).

What it means

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.

Source

Thrown at backend/app/gateway/routers/agents.py:95

    tool_groups: list[str] | None = Field(default=None, description="Updated tool group whitelist")
    skills: list[str] | None = Field(default=None, description="Updated skill whitelist (None=all, []=none)")
    model_settings: AgentModelSettings | None = Field(default=None, description="Updated per-agent sampling overrides")
    thinking_enabled: bool | None = Field(default=None, description="Updated per-agent thinking-mode default")
    reasoning_effort: ReasoningEffort | None = Field(default=None, description="Updated per-agent reasoning-effort default")
    soul: str | None = Field(default=None, description="Updated SOUL.md content")


def _validate_agent_name(name: str) -> None:
    """Validate agent name against allowed pattern.

    Args:
        name: The agent name to validate.

    Raises:
        HTTPException: 422 if the name is invalid.
    """
    if not AGENT_NAME_PATTERN.match(name):
        raise HTTPException(
            status_code=422,
            detail=f"Invalid agent name '{name}'. Must match ^[A-Za-z0-9-]+$ (letters, digits, and hyphens only).",
        )


def _normalize_agent_name(name: str) -> str:
    """Normalize agent name to lowercase for filesystem storage."""
    return name.lower()


def _require_agents_api_enabled() -> None:
    """Reject access unless the custom-agent management API is explicitly enabled."""
    if not get_agents_api_config().enabled:
        raise HTTPException(
            status_code=403,
            detail=("Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP."),
        )

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Slugify the name before the call: lowercase, replace whitespace/underscores with hyphens, strip non `[A-Za-z0-9-]` characters
2. Run the same regex client-side and block submission early with a helpful message
3. Use `/agents/check` to validate availability and format before creating

Example fix

// before
await api.createAgent({ name: 'My Cool Agent' }); // 422
// after
const name = 'My Cool Agent'.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
await api.createAgent({ name }); // 'my-cool-agent'

import re
AGENT_NAME_RE = re.compile(r'^[A-Za-z0-9-]+$')
if not AGENT_NAME_RE.fullmatch(name):
    raise ValueError(f'invalid agent name: {name!r}')

const isValidAgentName = (n: string): boolean => /^[A-Za-z0-9-]+$/.test(n);

try { await api.createAgent(body); }
catch (e) {
  if (e.status === 422 && /agent name/i.test(e.detail)) { showNameError(slugify(name)); return; }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown model '{model}'. Use a model name defined under `mod
• Password is too common; choose a stronger password.
• Unsupported context_mode
• reuse_thread requires thread_id
• Unsupported schedule_type

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/b0e575e239cbc602. Report an issue: GitHub.