{"record":{"id":"2837b1d100445cf1","repo":"langgenius/dify","slug":"agent-not-found","errorCode":null,"errorMessage":"Agent not found.","messagePattern":"Agent not found\\.","errorType":"http","errorClass":"AgentNotFoundError","httpStatus":404,"severity":"error","filePath":"api/controllers/console/agent/roster.py","lineNumber":388,"sourceCode":"    roster_service = _agent_roster_service(session)\n    payload = AgentAppDetailWithSite.model_validate(\n        app_model,\n        from_attributes=True,\n        context={\"session\": session},\n    ).model_dump(mode=\"json\")\n    agent = (\n        session.scalar(\n            select(Agent).where(\n                Agent.tenant_id == app_model.tenant_id,\n                Agent.id == agent_id,\n                Agent.status == AgentStatus.ACTIVE,\n            )\n        )\n        if agent_id\n        else roster_service.get_app_backing_agent(tenant_id=app_model.tenant_id, app_id=str(app_model.id))\n    )\n    if not agent:\n        raise AgentNotFoundError()\n    payload.pop(\"bound_agent_id\", None)\n    payload[\"app_id\"] = agent.app_id\n    payload[\"backing_app_id\"] = roster_service.runtime_backing_app_id(agent)\n    payload[\"hidden_app_backed\"] = bool(agent.backing_app_id and agent.backing_app_id != agent.app_id)\n    payload[\"id\"] = agent.id\n    debug_conversation_id = roster_service.get_or_create_build_conversation(\n        tenant_id=app_model.tenant_id,\n        agent_id=agent.id,\n        account_id=current_user.id,\n        commit=False,\n    )\n    message_count = roster_service.count_agent_app_debug_conversation_messages(\n        conversation_id=debug_conversation_id,\n    )\n    payload[\"debug_conversation_id\"] = debug_conversation_id\n    payload[\"debug_conversation_has_messages\"] = message_count > 0\n    payload[\"debug_conversation_message_count\"] = message_count\n    payload[\"role\"] = agent.role or \"\"","sourceCodeStart":370,"sourceCodeEnd":406,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/api/controllers/console/agent/roster.py#L370-L406","documentation":"Raised as AgentNotFoundError when serializing an Agent App detail: neither the direct Agent lookup (by agent_id) nor roster_service.get_app_backing_agent returned an Agent. The App exists (it passed setup/login) but has no ACTIVE Agent backing it, so the roster-shaped detail cannot be built. This is an inconsistency between the App row and the Agent roster.","triggerScenarios":"GET /console/agents/<agent_id>/apps/<app_id> (or the app detail serializer) for an App whose bound_agent_id points to a non-ACTIVE or missing Agent, or whose backing-agent lookup returns None. Distinguishable from 200/201 because it fires in the detail serializer, not the publish-visibility path.","commonSituations":"App whose Agent was soft-deleted or set to a non-ACTIVE status; app created by an older flow that did not provision the backing Agent; cross-tenant reference; race during Agent deactivation while the detail page is open.","solutions":["Confirm an ACTIVE Agent exists for the App: SELECT * FROM agents WHERE app_id=<app_id> AND status='active'; re-create/re-publish if missing.","If the Agent was intentionally deactivated, archive the App or rebind it to an active Agent.","Check bound_agent_id on the App row matches an existing Agent in the same tenant.","In fixtures, ensure the backing Agent row is created and ACTIVE before hitting the detail endpoint."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from sqlalchemy import select\nfrom models.agent import Agent, AgentStatus\n\ndef app_has_active_agent(session, app_model) -> bool:\n    return session.scalar(\n        select(Agent.id).where(\n            Agent.tenant_id == app_model.tenant_id,\n            Agent.app_id == app_model.id,\n            Agent.status == AgentStatus.ACTIVE,\n        ).limit(1)\n    ) is not None","typeGuard":null,"tryCatchPattern":"from services.errors.agent import AgentNotFoundError\n\ntry:\n    detail = fetch_agent_app_detail(app_id)\nexcept AgentNotFoundError:\n    # backing Agent missing/non-ACTIVE: rebind or restore before retry\n    raise","preventionTips":["Keep the backing Agent ACTIVE for any App exposed in the roster.","When deactivating an Agent, also archive or rebind the App.","In fixtures, create the ACTIVE backing Agent before hitting the detail endpoint."],"tags":["agent-roster","not-found","app-detail","state-machine"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}