theonedev/onedev · warning · ExplicitException

Cannot find server managing allocated agent, please retry la

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.

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)

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

• Criteria '' is not supported here
• Unexpected operator:
• Unable to find agent {0}
• Agent disconnected
• Workspace server not found

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