theonedev/onedev · error · ExplicitException

Unable to read log: agent is offline

Error message

Unable to read log: agent is offline

What it means

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.

Source

Thrown at server-core/src/main/java/io/onedev/server/web/resource/AgentLogResource.java:44

public class AgentLogResource extends AbstractResource {

	private static final long serialVersionUID = 1L;

	private static final String PARAM_AGENT = "agent";
	
	@Override
	protected ResourceResponse newResourceResponse(Attributes attributes) {
		if (!SecurityUtils.isAdministrator()) 
			throw new UnauthorizedException();

		String agentName = attributes.getParameters().get(PARAM_AGENT).toString();
		Agent agent = OneDev.getInstance(AgentService.class).findByName(agentName);
		if (agent == null)
			throw new EntityNotFoundException("Unable to find agent: " + agentName);
		
		if (!agent.isOnline())
			throw new ExplicitException("Unable to read log: agent is offline");
		
		ResourceResponse response = new ResourceResponse();
		response.setContentType(MimeTypes.OCTET_STREAM);
		
		response.disableCaching();
		
		try {
			response.setFileName(URLEncoder.encode("agent-log.txt", StandardCharsets.UTF_8.name()));
		} catch (UnsupportedEncodingException e) {
			throw new RuntimeException(e);
		}
		Long agentId = agent.getId();
		response.setWriteCallback(new WriteCallback() {

			@Override
			public void writeData(Attributes attributes) throws IOException {
				Agent agent = OneDev.getInstance(AgentService.class).load(agentId);
				List<String> agentLog = OneDev.getInstance(AgentService.class).getAgentLog(agent);

View on GitHub (pinned to d44925c47c)

Solutions

1. Start/reconnect the agent (check agent service status and its connection to the server), then retry.
2. Verify network/firewall connectivity between agent and server (agent token/URL still valid).
3. Add retry-with-delay logic in automation so it waits for the agent to come online before pulling logs.
4. If the agent was intentionally retired, remove it and its log requests.

Example fix

// before: immediate fetch
resp = fetchAgentLog(agentName);

// after: wait until online
await waitUntil(() -> agentService.findByName(agentName).isOnline(), 60, SECONDS);
resp = fetchAgentLog(agentName);

// Wait for the agent to be online before reading the log
Agent agent = OneDev.getInstance(AgentService.class).findByName(agentName);
if (agent == null || !agent.isOnline())
    return; // defer log fetch until online

try {
    readAgentLog(agentName);
} catch (ExplicitException e) {
    if (e.getMessage().contains("offline")) {
        Thread.sleep(5000); // retry after agent reconnects
        readAgentLog(agentName);
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to update attributes as agent is offline
• Allocated agent not connected to current server, please retr
• Not authorized
• Criteria '' is not supported here
• Unexpected operator:

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/bea31265d207ad3f. Report an issue: GitHub.