bytedance/deer-flow · error · HTTPException

Failed to list agents: {str(e)}

Error message

Failed to list agents: {str(e)}

What it means

Catch-all 500 when `list_custom_agents` or the per-agent SOUL/config enrichment inside the worker thread raises anything other than nothing (there is no narrower handler on this path). The store read is filesystem IO or DB round trips run via `asyncio.to_thread`; the original exception is logged with traceback, and its string form is echoed into the detail.

Source

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

    Returns:
        List of all custom agents with their metadata and soul content.
    """
    _require_agents_api_enabled()

    user_id = get_effective_user_id()

    def _list() -> AgentsListResponse:
        # Worker thread: the store read plus the per-agent SOUL read inside
        # _agent_config_to_response are filesystem IO (file backend) or DB round
        # trips (db backend) and must stay off the event loop.
        agents = list_custom_agents(user_id=user_id)
        return AgentsListResponse(agents=[_agent_config_to_response(a, include_soul=True, user_id=user_id) for a in agents])

    try:
        return await asyncio.to_thread(_list)
    except Exception as e:
        logger.error(f"Failed to list agents: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to list agents: {str(e)}")


@router.get(
    "/agents/check",
    summary="Check Agent Name",
    description="Validate an agent name and check if it is available (case-insensitive).",
)
async def check_agent_name(name: str) -> dict:
    """Check whether an agent name is valid and not yet taken.

    Args:
        name: The agent name to check.

    Returns:
        ``{"available": true/false, "name": "<normalized>"}``

    Raises:
        HTTPException: 422 if the name is invalid.

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check the Gateway logs — `exc_info=True` means the full traceback of the root cause is there
2. Validate/repair agent config files on disk (YAML parse each `config.yaml` under the agents dir)
3. For DB backends, verify DB connectivity and that migrations are current
4. Fix file ownership/permissions on the agents data directory

try { return await api.listAgents(); }
catch (e) {
  if (e.status === 500 && /Failed to list agents/.test(e.detail)) {
    logger.error('agent store unreadable', e);
    return { agents: [], degraded: true }; // surface degraded state, don't crash UI
  }
  throw e;
}

When it happens

Trigger: Corrupted agent config.yaml on disk (unparseable YAML); a DB-backed agent store with connectivity/credentials issues; permission errors reading per-user agent directories; partial writes from a crashed earlier create.

Common situations: Operators hand-editing agent config files and breaking YAML; database migrations that leave the agents table schema mismatched; container runs where volume permissions changed under the data dir.

Related errors

• Failed to update agent: {str(e)}
• Failed to get agent: {str(e)}
• Failed to create agent: {str(e)}
• Failed to create memory fact.
• Failed to read user profile: {str(e)}

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