theonedev/onedev · error · ExplicitException

Allocated agent not connected to current server, please retr

Error message

Allocated agent not connected to current server, please retry later

What it means

When a build step runs 'test' on an allocated cloud agent, the server verifies the agent has an active session connected to the current (this) server. If the agent session lookup returns null the agent is not connected here, and an ExplicitException is thrown and logged to the build.

Source

Thrown at server-core/src/main/java/io/onedev/server/agent/AgentHelper.java:46

		var token = testData.getToken();
		getLogService().addLogger(token, logger);
		try {
			String testServer = getClusterService().getLocalServerAddress();
			logger.log("Pending resource allocation...");
			getResourceService().submitAgentTask(
					null,
					AgentQuery.parse(agentQuery, true),
					resourceName,
					concurrency,
					1,
					agentId -> {
						TaskLogger currentLogger = new ServerLogger(testServer, token);
						var agentData = getSessionService().call(
								() -> getAgentService().load(agentId).getAgentData());

						Session agentSession = getAgentService().getAgentSession(agentId);
						if (agentSession == null) {
							throw new ExplicitException(
									"Allocated agent not connected to current server, please retry later");
						}

						currentLogger.log(String.format("Testing on agent '%s'...", agentData.getName()));

						if (getLogService().getLogger(token) == null) {
							getLogService().addLogger(token, currentLogger);
							try {
								return testCallAgent(agentSession, testData, token);
							} finally {
								getLogService().removeLogger(token);
							}
						} else {
							return testCallAgent(agentSession, testData, token);
						}
					}).get();
		} catch (InterruptedException | ExecutionException e) {
			throw new RuntimeException(e);

View on GitHub (pinned to d44925c47c)

Solutions

1. Retry the build/step later — the message itself says 'please retry later' once the agent reconnects.
2. Check the agent's status and logs; restart the agent so it re-establishes its session with the server.
3. In a cluster setup, verify the agent connects to the same server node handling the build (check load balancer/session affinity).
4. Verify network connectivity between agent and server port; fix dropped connections.

Example fix

// retry pattern around test call
try {
    agentHelper.test(...);
} catch (ExplicitException e) {
    if (e.getMessage().contains("Allocated agent not connected")) {
        // wait and retry or reschedule the job
    }
}

AgentSession s = getAgentService().getAgentSession(agentId);
if (s == null) {
    // reschedule the step instead of calling test
}

try {
    agentHelper.test(agentId, token, ...);
} catch (ExplicitException e) {
    if (e.getMessage().contains("Allocated agent not connected")) {
        // wait/backoff and retry, or reschedule the job
    }
}

When it happens

Trigger: Calling AgentHelper.test for an agent id that was allocated (assigned to a build/step) but whose websocket/agent session is not registered on the current server, e.g. after agent restart or in a cluster where the agent is connected to a different server node.

Common situations: Agent process crashed or was restarted mid-allocation, load balancer routed the build to a server node other than the one the agent connected to, network drop between agent and server, or a stale agent record.

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

• Agent disconnected
• This workspace is provisioned on agent previously, and canno
• Attachment not found:
• Malformed build spec
• This build is not authorized to sync to project:

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