JeffreySu/WeiXinMPSDK · error · ArgumentException

商品券图片仅支持 JPG、JPEG、BMP 或 PNG。

Error message

商品券图片仅支持 JPG、JPEG、BMP 或 PNG。

What it means

ProductCouponApis.ValidateImageFileName validates the extension of an image file name before uploading a product coupon (商品券) image to WeChat Pay. WeChat's API only accepts JPG, JPEG, BMP, or PNG images; anything else throws ArgumentException naming the offending parameter (fileName).

Solutions

1. Convert the image to PNG, JPG/JPEG, or BMP before calling UploadImageAsync.
2. Pass a fileName whose extension is exactly one of .jpg/.jpeg/.bmp/.png (Path.GetExtension-based check).
3. If the file has a query string or unusual casing, strip it or rename before upload.

Example fix

// before
await apis.UploadImageAsyncAsync("banner.webp", stream);
// after
var converted = ImageToPng("banner.webp");
await apis.UploadImageAsyncAsync("banner.png", converted);

var ext = Path.GetExtension(fileName)?.ToLowerInvariant();
if (ext != ".jpg" && ext != ".jpeg" && ext != ".bmp" && ext != ".png")
    throw new ArgumentException($"不支持的图片格式: {ext}，请转换为 JPG/BMP/PNG", nameof(fileName));

try { await apis.UploadImageAsyncAsync(fileName, stream); }
catch (ArgumentException ex) { logger.Warn(ex, "商品券图片格式不支持"); /* convert or prompt user */ }

When it happens

Trigger: Calling UploadImageAsync with a file whose extension is not .jpg/.jpeg/.bmp/.png (e.g. .gif, .webp, .GIF with no extension match, or a lowercase/uppercase mismatch the code doesn't normalize).

Common situations: Developers exporting marketing images as WebP or GIF from design tools, or passing URLs/paths with query strings appended to the file name so the extension check fails.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• 方法路径不能为空
• ArgumentOutOfRangeException (length must be >= 0)
• 请求未提供 sig 时必须提供收银台 API 调用密钥。
• 收银台 API 调用密钥不能为空。
• BotID 不能为空。

AI-assisted analysis of JeffreySu/WeiXinMPSDK@be573f6f94 (2026-09-12). Data as JSON: /api/errors/09b59f2d6590916b. Report an issue: GitHub.

Appendix: source

Thrown at src/Senparc.Weixin.TenPay/Senparc.Weixin.TenPayV3/Apis/ProductCoupon/ProductCouponApis.cs:821

        }

        private static void ValidateImageFileName(string fileName)
        {
            if (string.IsNullOrWhiteSpace(fileName))
            {
                throw new ArgumentException("文件名不能为空。",
                    nameof(fileName));
            }

            switch (Path.GetExtension(fileName)?.ToLowerInvariant())
            {
                case ".jpg":
                case ".jpeg":
                case ".bmp":
                case ".png":
                    return;
                default:
                    throw new ArgumentException(
                        "商品券图片仅支持 JPG、JPEG、BMP 或 PNG。",
                        nameof(fileName));
            }
        }
    }
}

View on GitHub (pinned to be573f6f94)