bytedance/deer-flow · error · HTTPException

Failed to get agent

Error message

Failed to get agent: {str(e)}

What it means

Catch-all 500 on GET `/agents/{name}`: the config was found (`FileNotFoundError` is handled separately as 404) but something during load or SOUL enrichment failed — e.g. config.yaml present but invalid, or the SOUL.md read raised a non-FileNotFoundError IO error. The real traceback is in the logs via `exc_info=True`.

Solutions

1. Read the Gateway log traceback to identify whether config parse or SOUL read failed
2. Open the agent's config.yaml on disk and fix or delete-and-recreate it
3. Restore correct file permissions on the agent directory
4. For DB backends, inspect the agent row for truncated/invalid payload

try { return await api.getAgent(name); }
catch (e) {
  if (e.status === 404) return null;               // absent
  if (e.status === 500) throw new CorruptAgentError(name, e.detail); // present but unreadable
  throw e;
}

When it happens

Trigger: A `config.yaml` that exists but fails schema validation or YAML parsing; permission denied reading SOUL.md; DB-backed store raising a data error after the row was found.

Common situations: Corrupted half-written config files (crash during a previous create/update); manual edits introducing invalid fields; permission changes on the data directory.

Related errors

• Failed to list agents
• Failed to update agent
• Failed to clear memory data.
• Failed to complete Lark connection setup.
• Failed to create agent

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

Appendix: source

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

        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.

    Returns:
        The created agent details.

View on GitHub (pinned to 1dd6ba1acb)