{"record":{"id":"37fc12c31a14ea71","repo":"theonedev/onedev","slug":"agent-disconnected","errorCode":null,"errorMessage":"Agent disconnected","messagePattern":"Agent disconnected","errorType":"exception","errorClass":"ExplicitException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/workspace/AgentProvisionerUtils.java","lineNumber":97,"sourceCode":"\t}\n\n\tpublic static void persistAgent(Long workspaceId, Long agentId) {\n\t\tOneDev.getInstance(TransactionService.class).run(() -> {\n\t\t\tvar workspaceService = OneDev.getInstance(WorkspaceService.class);\n\t\t\tvar workspace = workspaceService.load(workspaceId);\n\t\t\tvar agent = getAgentService().load(agentId);\n\t\t\tif (!agent.equals(workspace.getAgent())) {\n\t\t\t\tworkspace.setAgent(agent);\n\t\t\t\tworkspaceService.update(workspace);\n\t\t\t}\n\t\t});\n\t}\n\n\t@Nullable\n\tpublic static Session getAgentSession(Long agentId, boolean mustExist) {\n\t\tSession session = getAgentService().getAgentSession(agentId);\n\t\tif (session == null && mustExist)\n\t\t\tthrow new ExplicitException(\"Agent disconnected\");\n\t\treturn session;\n\t}\n\n\tprivate static AgentService getAgentService() {\n\t\treturn OneDev.getInstance(AgentService.class);\n\t}\n\n\tprivate static ResourceService getResourceService() {\n\t\treturn OneDev.getInstance(ResourceService.class);\n\t}\n\n}\n","sourceCodeStart":79,"sourceCodeEnd":110,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/workspace/AgentProvisionerUtils.java#L79-L110","documentation":"getAgentSession fetches the live connection session of an agent; when mustExist is true and the agent has no active session (agent offline/disconnected), it throws ExplicitException('Agent disconnected'). Provisioning and other agent-dependent operations cannot proceed without the connection.","triggerScenarios":"Calling AgentProvisionerUtils.getAgentSession(agentId, true) for an agent that is currently offline, or whose connection dropped and hasn't reconnected.","commonSituations":"Agent process stopped/crashed during a job; network outage between agent and server; agent container restarted without re-registering; targeting an agent that was decommissioned.","solutions":["Restart the agent so it reconnects to the server, then retry the operation.","Check the agent's status in Administration > Agents and investigate its connection/log.","Verify network connectivity (agent to server port) and firewall rules.","If the agent is gone, retarget the job/resource to an online agent."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// check agent status via API before use: GET /~api/agents -> agent online / session present","typeGuard":null,"tryCatchPattern":"try { getAgentSession(agentId, true); } catch (ExplicitException e) { /* wait/backoff, restart agent, then retry */ }","preventionTips":["Monitor agent liveness and auto-restart agents.","Check agent connectivity before dispatching jobs.","Alert on agents offline in Administration > Agents."],"tags":["agent","connectivity","cluster"],"backgroundTag":"connection-refused","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}