multica-ai/multica · error

file too large: %d bytes (max 5MB)

Error message

file too large: %d bytes (max 5MB)

What it means

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.

Source

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

	}

	// Validate file exists.
	info, err := os.Stat(filePath)
	if err != nil {
		return fmt.Errorf("file not found: %w", err)
	}

	// Validate extension.
	ext := strings.ToLower(filepath.Ext(filePath))
	validExts := map[string]bool{".png": true, ".jpg": true, ".jpeg": true, ".gif": true, ".webp": true}
	if !validExts[ext] {
		return fmt.Errorf("unsupported file format %q: must be .png, .jpg, .jpeg, .gif, or .webp", ext)
	}

	// Client-side size guard: reject files > 5MB.
	const maxSize = 5 << 20 // 5 MB
	if info.Size() > maxSize {
		return fmt.Errorf("file too large: %d bytes (max 5MB)", info.Size())
	}

	fileData, err := os.ReadFile(filePath)
	if err != nil {
		return fmt.Errorf("read file: %w", err)
	}

	// 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

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Downscale/re-encode: `magick big.jpg -resize 512x512 -quality 85 small.jpg`
2. Strip metadata and optimize: `magick big.png -strip png8.png` or `oxipng`
3. Confirm the result: `ls -l small.jpg` (must be ≤ 5,242,880 bytes) before retrying

Example fix

# before
multica agent avatar agt_1 --file photo_raw.jpg   # 9MB
# Error: file too large: 9437184 bytes (max 5MB)

# after
magick photo_raw.jpg -resize 512x512 -quality 85 avatar.jpg
multica agent avatar agt_1 --file avatar.jpg

size=$(stat -c %s "$AVATAR_FILE")
[ "$size" -le 5242880 ] || { echo "file is $size bytes; resize to under 5MB"; exit 1; }

const maxAvatarBytes = 5 << 20

func withinAvatarSize(info fs.FileInfo) bool {
	return info.Size() <= maxAvatarBytes
}

if info.Size() > maxSize {
	return fmt.Errorf("file too large: %d bytes (max 5MB)", info.Size())
}

When it happens

Trigger: `--file` pointing at a high-resolution photo, animated GIF, or PNG export larger than 5,242,880 bytes.

Common situations: Full-resolution camera photos, uncompressed screenshots, long GIF animations — common when avatars are prepared outside the usual web-resize pipeline.

Related errors

• unsupported file format %q: must be .png, .jpg, .jpeg, .gif,
• --file is required
• file not found: %w
• --cutoff is required; use the hosted deployment time of the
• parse --cutoff as RFC3339: %w

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