{"record":{"id":"bea31265d207ad3f","repo":"theonedev/onedev","slug":"unable-to-read-log-agent-is-offline","errorCode":null,"errorMessage":"Unable to read log: agent is offline","messagePattern":"Unable to read log: agent is offline","errorType":"exception","errorClass":"ExplicitException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/web/resource/AgentLogResource.java","lineNumber":44,"sourceCode":"\npublic class AgentLogResource extends AbstractResource {\n\n\tprivate static final long serialVersionUID = 1L;\n\n\tprivate static final String PARAM_AGENT = \"agent\";\n\t\n\t@Override\n\tprotected ResourceResponse newResourceResponse(Attributes attributes) {\n\t\tif (!SecurityUtils.isAdministrator()) \n\t\t\tthrow new UnauthorizedException();\n\n\t\tString agentName = attributes.getParameters().get(PARAM_AGENT).toString();\n\t\tAgent agent = OneDev.getInstance(AgentService.class).findByName(agentName);\n\t\tif (agent == null)\n\t\t\tthrow new EntityNotFoundException(\"Unable to find agent: \" + agentName);\n\t\t\n\t\tif (!agent.isOnline())\n\t\t\tthrow new ExplicitException(\"Unable to read log: agent is offline\");\n\t\t\n\t\tResourceResponse response = new ResourceResponse();\n\t\tresponse.setContentType(MimeTypes.OCTET_STREAM);\n\t\t\n\t\tresponse.disableCaching();\n\t\t\n\t\ttry {\n\t\t\tresponse.setFileName(URLEncoder.encode(\"agent-log.txt\", StandardCharsets.UTF_8.name()));\n\t\t} catch (UnsupportedEncodingException e) {\n\t\t\tthrow new RuntimeException(e);\n\t\t}\n\t\tLong agentId = agent.getId();\n\t\tresponse.setWriteCallback(new WriteCallback() {\n\n\t\t\t@Override\n\t\t\tpublic void writeData(Attributes attributes) throws IOException {\n\t\t\t\tAgent agent = OneDev.getInstance(AgentService.class).load(agentId);\n\t\t\t\tList<String> agentLog = OneDev.getInstance(AgentService.class).getAgentLog(agent);","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/web/resource/AgentLogResource.java#L26-L62","documentation":"AgentLogResource can only stream logs from a connected (online) agent. If the resolved agent is currently offline, it throws this ExplicitException because there is no live connection to read the log from.","triggerScenarios":"Requesting the log of an agent whose isOnline() is false at the moment of the request — the agent process is stopped, disconnected, or still starting up.","commonSituations":"Agent machine was shut down or network dropped; agent service stopped/crashed; request fired by automation immediately after agent restart before it reconnects; server restarted and agents have not re-registered yet.","solutions":["Start/reconnect the agent (check agent service status and its connection to the server), then retry.","Verify network/firewall connectivity between agent and server (agent token/URL still valid).","Add retry-with-delay logic in automation so it waits for the agent to come online before pulling logs.","If the agent was intentionally retired, remove it and its log requests."],"exampleFix":"// before: immediate fetch\nresp = fetchAgentLog(agentName);\n\n// after: wait until online\nawait waitUntil(() -> agentService.findByName(agentName).isOnline(), 60, SECONDS);\nresp = fetchAgentLog(agentName);","handlingStrategy":"retry","validationCode":"// Wait for the agent to be online before reading the log\nAgent agent = OneDev.getInstance(AgentService.class).findByName(agentName);\nif (agent == null || !agent.isOnline())\n    return; // defer log fetch until online","typeGuard":null,"tryCatchPattern":"try {\n    readAgentLog(agentName);\n} catch (ExplicitException e) {\n    if (e.getMessage().contains(\"offline\")) {\n        Thread.sleep(5000); // retry after agent reconnects\n        readAgentLog(agentName);\n    } else throw e;\n}","preventionTips":["Monitor agent connectivity; alert when agents drop offline.","Ensure agent services auto-start (systemd/Windows service) after reboots.","Add backoff/retry in automation that pulls logs from agents."],"tags":["agent","offline","log"],"backgroundTag":"agent-offline","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}