bytedance/deer-flow · warning · HTTPException

Agent '{name}' not found

Error message

Agent '{name}' not found

What it means

404 from GET `/agents/{name}`: name passed validation, but `load_agent_config` raised `FileNotFoundError` — no config exists for that (lowercased) name scoped to the current effective user. Names are normalized to lowercase before lookup, so 'MyAgent' and 'myagent' share one namespace.

Source

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

        Agent details including SOUL.md content.

    Raises:
        HTTPException: 404 if agent not found.
    """
    _require_agents_api_enabled()
    _validate_agent_name(name)
    name = _normalize_agent_name(name)
    user_id = get_effective_user_id()

    def _get() -> AgentResponse:
        # Worker thread: config read + SOUL read must stay off the event loop.
        agent_cfg = load_agent_config(name, user_id=user_id)
        return _agent_config_to_response(agent_cfg, include_soul=True, user_id=user_id)

    try:
        return await asyncio.to_thread(_get)
    except FileNotFoundError:
        raise HTTPException(status_code=404, detail=f"Agent '{name}' not found")
    except Exception as e:
        logger.error(f"Failed to get agent '{name}': {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to get agent: {str(e)}")


@router.post(
    "/agents",
    response_model=AgentResponse,
    status_code=201,
    summary="Create Custom Agent",
    description="Create a new custom agent with its config and SOUL.md.",
)
async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
    """Create a new custom agent.

    Args:
        request: The agent creation request.

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Re-list agents (GET `/agents`) to see what actually exists for this user
2. If the agent should exist, confirm you are authenticated as the user who created it
3. Handle 404 in the UI by refreshing the agent list and removing dead references

const existing = (await api.listAgents()).agents.map((a) => a.name);
if (!existing.includes(name.toLowerCase())) {
  // don't call GET — refresh the list instead
}

try { return await api.getAgent(name); }
catch (e) {
  if (e.status === 404) { await refreshAgentList(); return null; }
  throw e;
}

When it happens

Trigger: GET `/agents/foo` after the agent was deleted; fetching an agent created by a different user_id (per-user isolation); requesting a name whose stored casing differs — lookup is case-insensitive via normalization, so this indicates genuine absence, not casing; stale frontend list after another tab deleted the agent.

Common situations: Out-of-date agent pickers; switching logged-in user and expecting to see another user's agents; delete-then-navigate races in the UI.

Related errors

• Agent '{name}' only exists in the legacy shared layout and i
• Artifact not found: {path}
• Skill file not found: {skill_file_path}
• File '{internal_path}' not found in skill archive
• Thread {thread_id} not found

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