theonedev/onedev · warning · ExplicitException

Cannot find server managing allocated agent, please retry…

Error message

Cannot find server managing allocated agent, please retry later

What it means

DefaultResourceService.submitAgentTask() allocates an agent by id from a pool, then looks up the server managing that agent via agentService.getAgentServer(agentId). If the lookup returns null — the agent's managing server is unknown at that moment (agent/server registration lag or stale allocation data) — an ExplicitException tells the caller to retry later.

Solutions

1. Retry submitAgentTask() after a short backoff — the message explicitly says 'please retry later'
2. Verify the agent and its server are online in the cluster admin page; restart/re-register the agent if stale
3. Check server cluster connectivity (ports, tokens) so server registration completes promptly
4. Upgrade/inspect OneDev server logs for agent registration errors during startup

Example fix

// before
resourceService.submitAgentTask(task); // may throw on transient state
// after
for (int i = 0; i < 5; i++) {
    try { resourceService.submitAgentTask(task); break; }
    catch (ExplicitException e) {
        if (!e.getMessage().contains("Cannot find server managing allocated agent")) throw e;
        Thread.sleep(2000L << i);
    }
}

// Pre-check agent/server health before submitting
var server = agentService.getAgentServer(agentId);
if (server == null) scheduleRetry(task);

try {
    resourceService.submitAgentTask(task);
} catch (ExplicitException e) {
    if (e.getMessage().contains("Cannot find server managing allocated agent"))
        retryWithBackoff(task, 5);
    else throw e;
}

When it happens

Trigger: Calling submitAgentTask() when the allocated agent id has no registered managing server in the cluster, e.g. the server record was not yet synced or the agent/server entry is stale during cluster startup or failover.

Common situations: Submitting build-agent tasks right after a cluster node joins/restarts before server registration completes; k8s/cloud bursts where agents register faster than server metadata; load-balanced fleet with temporarily inconsistent agent-server mapping.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Agent disconnected
• Criteria '' is not supported here
• Unable to find agent
• Unexpected operator:
• Workspace runtime not found

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

Appendix: source

Thrown at server-core/src/main/java/io/onedev/server/service/impl/DefaultResourceService.java:307

			if (pinnedAgentId != null) {
				agentIds = new HashSet<>();
				var agent = agentService.get(pinnedAgentId);
				if (agent != null && agent.isOnline() && !agent.isPaused())
					agentIds.add(pinnedAgentId);
			} else {
				agentIds = agentService.query(agentQuery, 0, MAX_VALUE)
						.stream().filter(it -> it.isOnline() && !it.isPaused())
						.map(AbstractEntity::getId)
						.collect(toSet());
			}
			var agentIdString = allocateNode(
					agentIds.stream().map(Object::toString).collect(toList()),
					resourceName, totalConcurrency, requiredConcurrency);
			var agentId = agentIdString != null? Long.valueOf(agentIdString): null;
			if (agentId != null) {
				var server = agentService.getAgentServer(agentId);
				if (server == null)
					throw new ExplicitException("Cannot find server managing allocated agent, please retry later");

				return clusterService.submitToServer(server, () -> {
					var effectiveTotalConcurrency = getEffectiveTotalConcurrency(agentIdString, totalConcurrency);
					var concurrencyKey = agentId + ":" + resourceName;
					acquireConcurrency(concurrencyKey, effectiveTotalConcurrency, requiredConcurrency);
					try {
						updateLastUsedDate(agentId);
						return task.call(agentId);
					} finally {
						releaseConcurrency(concurrencyKey, requiredConcurrency);
					}
				});
			}
			try {
				Thread.sleep(1000);
			} catch (InterruptedException e) {
				throw new RuntimeException(e);
			}

View on GitHub (pinned to d44925c47c)