{"record":{"id":"3132b1a3066239d2","repo":"theonedev/onedev","slug":"unable-to-update-attributes-as-agent-is-offline","errorCode":null,"errorMessage":"Unable to update attributes as agent is offline","messagePattern":"Unable to update attributes as agent is offline","errorType":"http","errorClass":"ExplicitException","httpStatus":400,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/rest/resource/AgentResource.java","lineNumber":89,"sourceCode":"    \t\t@QueryParam(\"offset\") @Api(example=\"0\") int offset, \n    \t\t@QueryParam(\"count\") @Api(example=\"100\") int count) {\n    \tif (!SecurityUtils.isAdministrator()) \n\t\t\tthrow new UnauthorizedException();\n\n\t\tvar parsedQuery = AgentQuery.parse(query, false);\n    \t\n    \treturn agentService.query(parsedQuery, offset, count);\n    }\n\t\n\t@Api(order=400)\n\t@Path(\"/{agentId}/attributes\")\n\t@POST\n    public Response updateAttributes(@PathParam(\"agentId\") Long agentId, Map<String, String> attributes) {\n    \tif (!SecurityUtils.isAdministrator()) \n\t\t\tthrow new UnauthorizedException();\n    \tAgent agent = agentService.load(agentId);\n    \tif (!agent.isOnline())\n    \t\tthrow new ExplicitException(\"Unable to update attributes as agent is offline\");\n\t\tvar oldAuditContent = VersionedXmlDoc.fromBean(agent.getAttributeMap()).toXML();\n\t\tagentAttributeService.syncAttributes(agent, attributes);\n\t\tagentService.attributesUpdated(agent);\n\t\tvar newAuditContent = VersionedXmlDoc.fromBean(agent.getAttributeMap()).toXML();\n\t\tauditService.audit(null, \"changed attributes of agent \\\"\" + agent.getName() + \"\\\" via RESTful API\", \n\t\t\t\toldAuditContent, newAuditContent);\n\t\treturn Response.ok().build();\n    }\n\t\n}\n","sourceCodeStart":71,"sourceCodeEnd":100,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/rest/resource/AgentResource.java#L71-L100","documentation":"In updateAttributes, after the administrator check, OneDev refuses to sync attributes when the target agent is offline, throwing ExplicitException with this message. Attribute changes are pushed to the live agent, so they can only be applied while it is connected.","triggerScenarios":"POST /~api/agents/{agentId}/attributes with admin credentials while the agent process is stopped, disconnected, or not yet registered/online.","commonSituations":"Updating attributes during agent maintenance window when the agent service is down; agent container crashed; typo'd agentId pointing to a decommissioned agent; firewall/network drop leaving the agent offline.","solutions":["Start the agent (or fix its connection) so it shows Online in Admin > Agents, then retry","Confirm the agentId refers to a currently connected agent (GET /~api/agents and check status)","If attributes must be changed offline, edit them when the agent reconnects or re-register the agent","Automate by waiting/polling until agent.isOnline() before posting"],"exampleFix":"// before\nPOST /~api/agents/7/attributes ...  // agent 7 offline\n// after\n# start agent service first, e.g.\nsystemctl start onedev-agent\n# then retry the POST once agent is online","handlingStrategy":"validation","validationCode":"// check agent connectivity before POST\nAgent a = adminClient.getAgent(agentId);\nif (!a.getStatus().equals(\"ONLINE\")) throw new IllegalStateException(\"Agent offline; attributes cannot be updated\");","typeGuard":"boolean canUpdateAttributes(Agent a) { return a.isOnline(); }","tryCatchPattern":"try { client.updateAttributes(id, attrs); } catch (ClientErrorException e) { if (String.valueOf(e.getResponse().readEntity(String.class)).contains(\"offline\")) scheduleRetryAfterReconnect(id); }","preventionTips":["Poll agent status until online before syncing attributes","Keep agent services monitored (systemd health checks)","Re-verify agentId against live agent list; remove stale agent records"],"tags":["rest-api","agent","offline","precondition"],"backgroundTag":"invalid-state-transition","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}