theonedev/onedev · error · ExplicitException

A valid agent token is expected

Error message

A valid agent token is expected

What it means

AgentLibResource serves the agent library files, and it authenticates callers using an agent token supplied with the request. When the token parameter is absent or does not match any registered agent, it throws this ExplicitException instead of serving the library.

Source

Thrown at server-core/src/main/java/io/onedev/server/web/resource/AgentLibResource.java:65

						
						for (File file: Bootstrap.getLibDir().listFiles()) {
							if (agentLibs.contains(file.getName())) 
								FileUtils.copyFileToDirectory(file, tempDir);
						}
						
						try(var os = attributes.getResponse().getOutputStream()) {
							TarUtils.tar(tempDir, os, false);
						}
					} finally {
						FileUtils.deleteDir(tempDir);
					}
				}				
				
			});

			return response;				
		} else {
			throw new ExplicitException("A valid agent token is expected");
		}
	}

}

View on GitHub (pinned to d44925c47c)

Solutions

1. Pass the current agent token with the request (the token shown in Admin > Agents when downloading/installing the agent).
2. If the token was reset, re-register or update the agent with the new token and retry.
3. Verify the download URL includes the token parameter exactly as provided by the server UI.

Example fix

// before
curl -O https://onedev/~agentlib/agent.jar

// after
curl -O "https://onedev/~agentlib/agent.jar?token=<agent-token>"

// Verify the token is present and current before requesting the lib
if (agentToken == null || agentToken.isBlank())
    throw new IllegalArgumentException("agent token required");
// fetch: "https://onedev/~agentlib/...?token=" + agentToken

When it happens

Trigger: Requesting the agent library resource without a valid agent token parameter, or with a token that no longer matches a registered agent (token regenerated on server or agent not registered).

Common situations: Agent token was reset on the server after the agent was installed; manual curl/wget download of the agent lib without the token query parameter; agent registration was deleted but the agent keeps requesting the lib; copy-pasting a URL missing the token parameter.

Related errors

• Unable to import build spec (import project: {0}, import rev
• No workspace context found for specified token
• Allocated agent not connected to current server, please retr
• Authentication required
• Unauthenticated

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