{"record":{"id":"b87b31b6661e9d6c","repo":"theonedev/onedev","slug":"a-valid-agent-token-is-expected","errorCode":null,"errorMessage":"A valid agent token is expected","messagePattern":"A valid agent token is expected","errorType":"exception","errorClass":"ExplicitException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/web/resource/AgentLibResource.java","lineNumber":65,"sourceCode":"\t\t\t\t\t\t\n\t\t\t\t\t\tfor (File file: Bootstrap.getLibDir().listFiles()) {\n\t\t\t\t\t\t\tif (agentLibs.contains(file.getName())) \n\t\t\t\t\t\t\t\tFileUtils.copyFileToDirectory(file, tempDir);\n\t\t\t\t\t\t}\n\t\t\t\t\t\t\n\t\t\t\t\t\ttry(var os = attributes.getResponse().getOutputStream()) {\n\t\t\t\t\t\t\tTarUtils.tar(tempDir, os, false);\n\t\t\t\t\t\t}\n\t\t\t\t\t} finally {\n\t\t\t\t\t\tFileUtils.deleteDir(tempDir);\n\t\t\t\t\t}\n\t\t\t\t}\t\t\t\t\n\t\t\t\t\n\t\t\t});\n\n\t\t\treturn response;\t\t\t\t\n\t\t} else {\n\t\t\tthrow new ExplicitException(\"A valid agent token is expected\");\n\t\t}\n\t}\n\n}\n","sourceCodeStart":47,"sourceCodeEnd":70,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/web/resource/AgentLibResource.java#L47-L70","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass the current agent token with the request (the token shown in Admin > Agents when downloading/installing the agent).","If the token was reset, re-register or update the agent with the new token and retry.","Verify the download URL includes the token parameter exactly as provided by the server UI."],"exampleFix":"// before\ncurl -O https://onedev/~agentlib/agent.jar\n\n// after\ncurl -O \"https://onedev/~agentlib/agent.jar?token=<agent-token>\"","handlingStrategy":"validation","validationCode":"// Verify the token is present and current before requesting the lib\nif (agentToken == null || agentToken.isBlank())\n    throw new IllegalArgumentException(\"agent token required\");\n// fetch: \"https://onedev/~agentlib/...?token=\" + agentToken","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Store the agent token in the agent's config and pass it on every lib request.","Re-download the token after resetting agent registration on the server.","Never hand-strip the token parameter from generated download URLs."],"tags":["agent","token","authentication"],"backgroundTag":"missing-credentials","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}