{"record":{"id":"cde6cf741a6f9039","repo":"bytedance/deer-flow","slug":"failed-to-create-agent-str-e","errorCode":null,"errorMessage":"Failed to create agent: {str(e)}","messagePattern":"Failed to create agent: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/app/gateway/routers/agents.py","lineNumber":347,"sourceCode":"    _apply_model_behavior(config_data, request)\n\n    store = get_agent_store()\n\n    def _create_agent() -> AgentResponse:\n        # Worker thread: existence checks + persistence (file IO or a DB round\n        # trip) must stay off the event loop.\n        store.create(normalized_name, config_data, request.soul, user_id=user_id)\n        logger.info(\"Created agent '%s'\", normalized_name)\n        agent_cfg = load_agent_config(normalized_name, user_id=user_id)\n        return _agent_config_to_response(agent_cfg, include_soul=True, user_id=user_id)\n\n    try:\n        return await asyncio.to_thread(_create_agent)\n    except AgentExistsError:\n        raise HTTPException(status_code=409, detail=f\"Agent '{normalized_name}' already exists\")\n    except Exception as e:\n        logger.error(f\"Failed to create agent '{request.name}': {e}\", exc_info=True)\n        raise HTTPException(status_code=500, detail=f\"Failed to create agent: {str(e)}\")\n\n\n@router.put(\n    \"/agents/{name}\",\n    response_model=AgentResponse,\n    summary=\"Update Custom Agent\",\n    description=\"Update an existing custom agent's config and/or SOUL.md.\",\n)\nasync def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:\n    \"\"\"Update an existing custom agent.\n\n    Args:\n        name: The agent name.\n        request: The update request (all fields optional).\n\n    Returns:\n        The updated agent details.\n","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/agents.py#L329-L365","documentation":"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.","triggerScenarios":"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.","commonSituations":"Container volume mounted with wrong uid; per-user directories created by root in a previous run; DB connection pool exhausted.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { return await api.createAgent(body); }\ncatch (e) {\n  if (e.status === 500) {\n    reportOps(`agent create failed: ${e.detail}`); // needs server-side log triage\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["http-500","agents","permissions","persistence"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}