theonedev/onedev · error · ExplicitException

Agent disconnected

Error message

Agent disconnected

What it means

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.

Source

Thrown at server-core/src/main/java/io/onedev/server/workspace/AgentProvisionerUtils.java:97

	}

	public static void persistAgent(Long workspaceId, Long agentId) {
		OneDev.getInstance(TransactionService.class).run(() -> {
			var workspaceService = OneDev.getInstance(WorkspaceService.class);
			var workspace = workspaceService.load(workspaceId);
			var agent = getAgentService().load(agentId);
			if (!agent.equals(workspace.getAgent())) {
				workspace.setAgent(agent);
				workspaceService.update(workspace);
			}
		});
	}

	@Nullable
	public static Session getAgentSession(Long agentId, boolean mustExist) {
		Session session = getAgentService().getAgentSession(agentId);
		if (session == null && mustExist)
			throw new ExplicitException("Agent disconnected");
		return session;
	}

	private static AgentService getAgentService() {
		return OneDev.getInstance(AgentService.class);
	}

	private static ResourceService getResourceService() {
		return OneDev.getInstance(ResourceService.class);
	}

}

View on GitHub (pinned to d44925c47c)

Solutions

1. Restart the agent so it reconnects to the server, then retry the operation.
2. Check the agent's status in Administration > Agents and investigate its connection/log.
3. Verify network connectivity (agent to server port) and firewall rules.
4. If the agent is gone, retarget the job/resource to an online agent.

// check agent status via API before use: GET /~api/agents -> agent online / session present

try { getAgentSession(agentId, true); } catch (ExplicitException e) { /* wait/backoff, restart agent, then retry */ }

When it happens

Trigger: Calling AgentProvisionerUtils.getAgentSession(agentId, true) for an agent that is currently offline, or whose connection dropped and hasn't reconnected.

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

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Allocated agent not connected to current server, please retr
• Cannot find server managing allocated agent, please retry la
• Unable to discover cluster ip from database connection url:
• Upload project not found:
• This api can only be accessed via cluster credential

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