multica-ai/multica · error

upload avatar: %w

Error message

upload avatar: %w

What it means

Wrapped error returned when the avatar bytes cannot be uploaded via client.UploadFileWithURL — the multipart/binary upload step of `multica agent avatar`, executed after the agent existence pre-check passes. Causes include network failure mid-upload, exceeding the 60s context timeout (cli.AtLeastAPITimeout), auth rejection on the upload endpoint, or a server-side content rejection (corrupt image data despite a valid extension).

Source

Thrown at server/cmd/multica/cmd_agent.go:956

	// Defensive re-check: guard against TOCTOU race where the file
	// was swapped between stat and read.
	if len(fileData) > maxSize {
		return fmt.Errorf("file too large: %d bytes (max 5MB)", len(fileData))
	}

	ctx, cancel := context.WithTimeout(context.Background(), cli.AtLeastAPITimeout(60*time.Second))
	defer cancel()

	// Agent existence pre-check.
	var agent map[string]any
	if err := client.GetJSON(ctx, "/api/agents/"+args[0], &agent); err != nil {
		return fmt.Errorf("get agent: %w", err)
	}

	id, url, err := client.UploadFileWithURL(ctx, fileData, filePath)
	if err != nil {
		return fmt.Errorf("upload avatar: %w", err)
	}

	body := map[string]any{"avatar_url": url}
	var result map[string]any
	if err := client.PutJSON(ctx, "/api/agents/"+args[0], body, &result); err != nil {
		return fmt.Errorf("update agent avatar: %w", err)
	}

	output, _ := cmd.Flags().GetString("output")
	if output == "json" {
		return cli.PrintJSON(os.Stdout, map[string]any{
			"id":         id,
			"agent_id":   args[0],
			"avatar_url": url,
		})
	}

	headers := []string{"ID", "AGENT_ID", "AVATAR_URL"}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Retry on a stable connection; check the server logs for the underlying upload error
2. Verify the file is genuinely the format its extension claims (`file avatar.png`), re-export if it is a renamed foreign format
3. If uploads consistently time out, use a smaller image (resize/re-encode) to finish well under 60s
4. Confirm the server's storage backend is healthy (its logs will show S3/local-storage errors)

Example fix

# before
multica agent avatar agt_1 --file renamed.bmp.png   # actually BMP bytes
# Error: upload avatar: 400: invalid image data

# after
magick renamed.bmp.png avatar.png
multica agent avatar agt_1 --file avatar.png

file "$AVATAR_FILE"   # confirm bytes match the extension
size=$(stat -c %s "$AVATAR_FILE"); [ "$size" -le 5242880 ] || exit 1

id, url, err := client.UploadFileWithURL(ctx, fileData, filePath)
if err != nil {
	return fmt.Errorf("upload avatar: %w", err) // transient network: safe to retry whole command
}

When it happens

Trigger: Slow or dropped connection during a ~5MB upload, server-side upload endpoint misconfigured (storage backend down), token lacking upload scope, or a renamed non-image file whose bytes fail server sniffing.

Common situations: Uploading over VPN/weak Wi-Fi, object storage (S3-compatible) credentials expired on the server, renamed .bmp to .png, large GIF approaching the timeout.

Related errors

• update agent avatar: %w
• upload attachment: %w
• install Private Plugin: %w
• create agent: %w
• update agent: %w

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/0919ca8caefebfdf. Report an issue: GitHub.