{"record":{"id":"0e5cd9085ae9761f","repo":"multica-ai/multica","slug":"update-agent-avatar-w","errorCode":null,"errorMessage":"update agent avatar: %w","messagePattern":"update agent avatar: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/cmd/multica/cmd_agent.go","lineNumber":962,"sourceCode":"\n\tctx, cancel := context.WithTimeout(context.Background(), cli.AtLeastAPITimeout(60*time.Second))\n\tdefer cancel()\n\n\t// Agent existence pre-check.\n\tvar agent map[string]any\n\tif err := client.GetJSON(ctx, \"/api/agents/\"+args[0], &agent); err != nil {\n\t\treturn fmt.Errorf(\"get agent: %w\", err)\n\t}\n\n\tid, url, err := client.UploadFileWithURL(ctx, fileData, filePath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"upload avatar: %w\", err)\n\t}\n\n\tbody := map[string]any{\"avatar_url\": url}\n\tvar result map[string]any\n\tif err := client.PutJSON(ctx, \"/api/agents/\"+args[0], body, &result); err != nil {\n\t\treturn fmt.Errorf(\"update agent avatar: %w\", err)\n\t}\n\n\toutput, _ := cmd.Flags().GetString(\"output\")\n\tif output == \"json\" {\n\t\treturn cli.PrintJSON(os.Stdout, map[string]any{\n\t\t\t\"id\":         id,\n\t\t\t\"agent_id\":   args[0],\n\t\t\t\"avatar_url\": url,\n\t\t})\n\t}\n\n\theaders := []string{\"ID\", \"AGENT_ID\", \"AVATAR_URL\"}\n\trows := [][]string{{\n\t\tid,\n\t\targs[0],\n\t\turl,\n\t}}\n\tcli.PrintTable(os.Stdout, headers, rows)","sourceCodeStart":944,"sourceCodeEnd":980,"githubUrl":"https://github.com/multica-ai/multica/blob/2c0912b6ec764b373d44eeea1e80f0d9f11ab417/server/cmd/multica/cmd_agent.go#L944-L980","documentation":"Final wrapped error in the avatar flow: after a successful upload the CLI PUTs {\"avatar_url\": url} to `/api/agents/{id}` to attach the URL to the agent. Failure at this point means the agent disappeared mid-flow, auth/session expired between calls, or the server rejected the avatar_url value — note the upload itself already succeeded and remains stored.","triggerScenarios":"Agent deleted or archived between the GET pre-check and the PUT; token expires during a slow upload; server rejects the returned upload URL format; transient 5xx during the update.","commonSituations":"Concurrent admin operations deleting the agent, long uploads crossing session expiry windows, server restarts mid-command.","solutions":["Verify the agent still exists (`multica agent get <id>`) and re-attach: the file is uploaded, so retry the full command (re-upload is cheap and idempotent in effect)","If sessions are expiring, re-authenticate and retry the whole `agent avatar` command","Check server logs if the PUT returns 400 for the avatar_url — a server/storage misconfiguration","Retry once for transient 5xx before investigating further"],"exampleFix":"# before (agent deleted mid-upload)\nmultica agent avatar agt_1 --file me.png\n# Error: update agent avatar: 404: agent not found\n\n# after\nmultica agent list                       # recreate/re-find agent\nmultica agent avatar agt_1 --file me.png # re-run; upload repeats cleanly","handlingStrategy":"retry","validationCode":"multica agent get \"$AGENT_ID\" >/dev/null 2>&1 || { echo 'agent missing; abort avatar flow'; exit 1; }","typeGuard":null,"tryCatchPattern":"if err := client.PutJSON(ctx, \"/api/agents/\"+args[0], body, &result); err != nil {\n\treturn fmt.Errorf(\"update agent avatar: %w\", err) // upload succeeded; rerun full command is safe\n}","preventionTips":["Avoid concurrent delete/archive operations while running avatar commands","Re-authenticate before long-running CLI sessions to prevent mid-flow expiry","On failure, just re-run the whole avatar command — the flow is effectively idempotent"],"tags":["cli","api","upload","avatar"],"backgroundTag":null,"analyzedSha":"2c0912b6ec764b373d44eeea1e80f0d9f11ab417","analyzedAt":"2026-08-15T13:25:18.241Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}