What causes "Failed to create agent: {str(e)}" in bytedance/deer-flow?

Check logs for the exact traceback (`Failed to create agent ' '`)

bytedance/deer-flow · error · HTTPException

Failed to create agent: {str(e)}

Error message

Failed to create agent: {str(e)}

What it means

Catch-all 500 on POST `/agents`: creation failed with something other than `AgentExistsError` — e.g. the store cannot write config.yaml/SOUL.md (permissions, disk full), the config payload fails serialization, or the post-create `load_agent_config` re-read fails. Root cause traceback is logged.

Source

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

    _apply_model_behavior(config_data, request)

    store = get_agent_store()

    def _create_agent() -> AgentResponse:
        # Worker thread: existence checks + persistence (file IO or a DB round
        # trip) must stay off the event loop.
        store.create(normalized_name, config_data, request.soul, user_id=user_id)
        logger.info("Created agent '%s'", normalized_name)
        agent_cfg = load_agent_config(normalized_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(_create_agent)
    except AgentExistsError:
        raise HTTPException(status_code=409, detail=f"Agent '{normalized_name}' already exists")
    except Exception as e:
        logger.error(f"Failed to create agent '{request.name}': {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to create agent: {str(e)}")


@router.put(
    "/agents/{name}",
    response_model=AgentResponse,
    summary="Update Custom Agent",
    description="Update an existing custom agent's config and/or SOUL.md.",
)
async def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:
    """Update an existing custom agent.

    Args:
        name: The agent name.
        request: The update request (all fields optional).

    Returns:
        The updated agent details.

View on GitHub (pinned to 1dd6ba1acb)

Solutions

Check logs for the exact traceback (`Failed to create agent '<name>'`)
Verify write permissions on the agents base dir for the Gateway process user
Free disk space if writes fail with ENOSPC
For DB backends, check DB health and migrations

Defensive patterns

Strategy: try-catch

Try / catch

try { return await api.createAgent(body); }
catch (e) {
  if (e.status === 500) {
    reportOps(`agent create failed: ${e.detail}`); // needs server-side log triage
  }
  throw e;
}

Prevention

Verify the Gateway process can write to the agents data dir before enabling the API
Alert on create-agent 500s — they almost always indicate storage/permission drift
Do not auto-retry a failed create blindly; the first attempt may have partially written files

When it happens

Trigger: Read-only or wrongly-owned agents data directory; disk exhaustion; invalid config_data fields that pass request validation but break the store's serializer; DB write failure.

Common situations: Container volume mounted with wrong uid; per-user directories created by root in a previous run; DB connection pool exhausted.

Related errors

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