multica-ai/multica · error

unsupported file format %q: must be .png, .jpg, .jpeg, .gif,

Error message

unsupported file format %q: must be .png, .jpg, .jpeg, .gif, or .webp

What it means

Returned by `multica agent avatar` when the lowercased extension of the file is not in {.png, .jpg, .jpeg, .gif, .webp}. The check is purely extension-based on the path — the actual bytes are not sniffed — so renaming a BMP to .png passes here and will be caught (or accepted) server-side later.

Source

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

		return err
	}

	filePath, _ := cmd.Flags().GetString("file")
	if filePath == "" {
		return fmt.Errorf("--file is required")
	}

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

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Convert the image to an allowed format: `magick input.heic output.png` (or `convert`/`sips`/an online converter)
2. Rename genuinely valid files whose extension is wrong: `mv avatar.avatar.png avatar.png`
3. Pick PNG for logos/screenshots and JPEG for photos to also keep size under the 5MB cap

Example fix

# before
multica agent avatar agt_1 --file logo.svg
# Error: unsupported file format ".svg": must be .png, .jpg, .jpeg, .gif, or .webp

# after
magick logo.svg logo.png
multica agent avatar agt_1 --file logo.png

case "$AVATAR_FILE" in
  *.png|*.jpg|*.jpeg|*.gif|*.webp) : ;;
  *) echo "unsupported format; convert to png/jpg/jpeg/gif/webp"; exit 1 ;;
esac

var validAvatarExt = map[string]bool{".png": true, ".jpg": true, ".jpeg": true, ".gif": true, ".webp": true}

func hasValidAvatarExt(path string) bool {
	return validAvatarExt[strings.ToLower(filepath.Ext(path))]
}

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

When it happens

Trigger: `--file avatar.bmp`, `--file avatar.svg`, `--file avatar.heic`, a file with no extension, or a double-suffixed name like `avatar.png.txt`.

Common situations: iPhone HEIC exports, SVG logos, screenshots saved as .tiff/.bmp, or designers handing off unsupported formats.

Related errors

• file not found: %w
• file too large: %d bytes (max 5MB)
• --file is required
• read file: %w
• --%s-file %q: empty contents%s

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