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

Read the traceback logged with `Failed to delete agent ' '`

bytedance/deer-flow · error · HTTPException

Failed to delete agent: {str(e)}

Error message

Failed to delete agent: {str(e)}

What it means

Catch-all 500 on DELETE `/agents/{name}`: `store.delete` itself raised — rmtree permission errors, DB delete failures — before any outcome classification. Note the distinction: outcome values 'legacy'/'missing'/'not-custom-agent' map to 409/404/409 respectively; this 500 means the delete operation threw rather than returning an outcome.

Source

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

    Args:
        name: The agent name.

    Raises:
        HTTPException: 404 if no per-user copy exists; 409 if only a legacy
            shared copy exists (suggesting the migration script).
    """
    _require_agents_api_enabled()
    _validate_agent_name(name)
    name = _normalize_agent_name(name)
    user_id = get_effective_user_id()
    store = get_agent_store()

    try:
        # Off the event loop: file rmtree or a DB delete plus memory cleanup.
        outcome = await asyncio.to_thread(store.delete, name, user_id=user_id)
    except Exception as e:
        logger.error(f"Failed to delete agent '{name}': {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to delete agent: {str(e)}")

    if outcome == "legacy":
        raise HTTPException(
            status_code=409,
            detail=(f"Agent '{name}' only exists in the legacy shared layout and is not scoped to a user. Run scripts/migrate_user_isolation.py to move legacy agents into the per-user layout before deleting."),
        )
    if outcome == "missing":
        raise HTTPException(status_code=404, detail=f"Agent '{name}' not found")
    if outcome == "not-custom-agent":
        raise HTTPException(
            status_code=409,
            detail=(f"Directory for '{name}' contains memory data but is not a custom agent because config.yaml is missing; it was preserved."),
        )

    logger.info(f"Deleted agent '{name}'")

View on GitHub (pinned to 1dd6ba1acb)

Solutions

Read the traceback logged with `Failed to delete agent '<name>'`
Fix ownership of the agent directory tree so the Gateway user can remove it, then retry
If a partial delete occurred, verify remaining files and clean up manually before re-creating
For DB backends, check DB health

Defensive patterns

Strategy: try-catch

Try / catch

try { await api.deleteAgent(name); }
catch (e) {
  if (e.status === 500 && /Failed to delete/.test(e.detail)) {
    const still = await api.listAgents(); // delete may have partially completed
    if (still.agents.some((a) => a.name === name)) throw new AgentDeleteFailedError(name);
    return; // actually gone despite the error
  }
  throw e;
}

Prevention

After a failed delete, verify with a fresh list — partial deletes happen
Keep agent directory ownership aligned with the Gateway process user
Alert on delete 500s; rmtree permission errors are the usual cause

When it happens

Trigger: Files under the agent dir owned by root so rmtree fails midway; DB connection dropped mid-delete; memory cleanup raising after config removal.

Common situations: Agents created by a different uid (earlier container run as root); NFS volume refusing recursive deletes; partial delete leaving the agent in a broken state.

Related errors

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