{"record":{"id":"44f5408d115a57e2","repo":"multica-ai/multica","slug":"file-too-large-d-bytes-max-5mb","errorCode":null,"errorMessage":"file too large: %d bytes (max 5MB)","messagePattern":"file too large: (.+?) bytes \\(max 5MB\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/cmd/multica/cmd_agent.go","lineNumber":931,"sourceCode":"\t}\n\n\t// Validate file exists.\n\tinfo, err := os.Stat(filePath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"file not found: %w\", err)\n\t}\n\n\t// Validate extension.\n\text := strings.ToLower(filepath.Ext(filePath))\n\tvalidExts := map[string]bool{\".png\": true, \".jpg\": true, \".jpeg\": true, \".gif\": true, \".webp\": true}\n\tif !validExts[ext] {\n\t\treturn fmt.Errorf(\"unsupported file format %q: must be .png, .jpg, .jpeg, .gif, or .webp\", ext)\n\t}\n\n\t// Client-side size guard: reject files > 5MB.\n\tconst maxSize = 5 << 20 // 5 MB\n\tif info.Size() > maxSize {\n\t\treturn fmt.Errorf(\"file too large: %d bytes (max 5MB)\", info.Size())\n\t}\n\n\tfileData, err := os.ReadFile(filePath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"read file: %w\", err)\n\t}\n\n\t// Defensive re-check: guard against TOCTOU race where the file\n\t// was swapped between stat and read.\n\tif len(fileData) > maxSize {\n\t\treturn fmt.Errorf(\"file too large: %d bytes (max 5MB)\", len(fileData))\n\t}\n\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","sourceCodeStart":913,"sourceCodeEnd":949,"githubUrl":"https://github.com/multica-ai/multica/blob/2c0912b6ec764b373d44eeea1e80f0d9f11ab417/server/cmd/multica/cmd_agent.go#L913-L949","documentation":"Client-side guard in `multica agent avatar` that rejects files whose stat size exceeds 5MB (5 << 20 bytes). It fires before the file is read or uploaded, mirroring the server's upload limit so large payloads fail fast locally.","triggerScenarios":"`--file` pointing at a high-resolution photo, animated GIF, or PNG export larger than 5,242,880 bytes.","commonSituations":"Full-resolution camera photos, uncompressed screenshots, long GIF animations — common when avatars are prepared outside the usual web-resize pipeline.","solutions":["Downscale/re-encode: `magick big.jpg -resize 512x512 -quality 85 small.jpg`","Strip metadata and optimize: `magick big.png -strip png8.png` or `oxipng`","Confirm the result: `ls -l small.jpg` (must be ≤ 5,242,880 bytes) before retrying"],"exampleFix":"# before\nmultica agent avatar agt_1 --file photo_raw.jpg   # 9MB\n# Error: file too large: 9437184 bytes (max 5MB)\n\n# after\nmagick photo_raw.jpg -resize 512x512 -quality 85 avatar.jpg\nmultica agent avatar agt_1 --file avatar.jpg","handlingStrategy":"validation","validationCode":"size=$(stat -c %s \"$AVATAR_FILE\")\n[ \"$size\" -le 5242880 ] || { echo \"file is $size bytes; resize to under 5MB\"; exit 1; }","typeGuard":"const maxAvatarBytes = 5 << 20\n\nfunc withinAvatarSize(info fs.FileInfo) bool {\n\treturn info.Size() <= maxAvatarBytes\n}","tryCatchPattern":"if info.Size() > maxSize {\n\treturn fmt.Errorf(\"file too large: %d bytes (max 5MB)\", info.Size())\n}","preventionTips":["Resize/re-encode images to a few hundred KB — avatars need no more","Check byte size with stat before invoking the CLI","Strip metadata; it can account for a surprising share of PNG size"],"tags":["cli","validation","file-size","image","avatar"],"backgroundTag":null,"analyzedSha":"2c0912b6ec764b373d44eeea1e80f0d9f11ab417","analyzedAt":"2026-08-15T13:25:18.241Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}