bytedance/deer-flow · error · HTTPException

Failed to get agent: {str(e)}

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`.

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)

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: {str(e)}
• Failed to update agent: {str(e)}
• Failed to create agent: {str(e)}
• Failed to read user profile: {str(e)}
• Failed to update user profile: {str(e)}

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