JeffreySu/WeiXinMPSDK · error · ArgumentOutOfRangeException

文件大小上限必须大于 0。

Error message

文件大小上限必须大于 0。

What it means

RequestMultipartCoreAsync validates that when maxFileBytes is supplied it must be strictly positive. If a caller passes 0 or a negative value, the library throws ArgumentOutOfRangeException because a non-positive upload limit is meaningless. This is a caller-side parameter contract error, not a server or network problem.

Solutions

1. Pass null (omit) for maxFileBytes when no limit is desired — 0 is not the 'unlimited' sentinel.
2. Check the configured/upload limit value before calling and ensure it is > 0.
3. Fix the calculation that produced the non-positive limit (e.g. guard against zero-size configs).
4. Wrap the call in try/catch for ArgumentOutOfRangeException during development to surface the bad parameter early.

Example fix

// before
await apiRequest.RequestMultipartWithMaxSizeAsync(url, jsonContent, fileStream, maxFileBytes: 0);
// after
await apiRequest.RequestMultipartWithMaxSizeAsync(url, jsonContent, fileStream, maxFileBytes: 5 * 1024 * 1024); // or null for unlimited

if (maxFileBytes.HasValue && maxFileBytes.Value <= 0)
    throw new ArgumentException("maxFileBytes must be positive or null for unlimited.", nameof(maxFileBytes));

bool IsValidMaxSize(long? maxFileBytes) => !maxFileBytes.HasValue || maxFileBytes.Value > 0;

When it happens

Trigger: Calling RequestMultipartAsync / RequestMultipartWithMaxSizeAsync / RequestMultipartWithFileDigestAsync / RequestMultipartWithFilenameAndFileDigestAsync with maxFileBytes = 0, negative, or a default-constructed value (e.g. int variable never assigned, or computed size limit that evaluated to <= 0).

Common situations: Passing 0 to mean 'no limit' (the library uses null for unlimited, not 0); computing the limit from configuration that resolved to 0; passing a negative due to a subtraction bug when deriving the cap.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• 请求体上限必须大于 0。
• 注册委托容量必须大于 0。
• 未知的 PlatformType ：
• 方法路径不能为空
• 无效的方法路径格式

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

Appendix: source

Thrown at src/Senparc.Weixin.TenPay/Senparc.Weixin.TenPayV3/HttpHandlers/TenPayApiRequest.cs:388

        private async Task<T> RequestMultipartCoreAsync<T>(string url, string fileName,
            Stream fileStream, CancellationToken cancellationToken,
            MultipartMetaFieldStyle metaFieldStyle, int timeOut, bool checkSign,
            Func<T> createDefaultInstance, int? maxFileBytes = null)
            where T : ReturnJsonBase, new()
        {
            if (string.IsNullOrWhiteSpace(fileName))
            {
                throw new ArgumentException("文件名不能为空。", nameof(fileName));
            }

            _ = fileStream ?? throw new ArgumentNullException(nameof(fileStream));
            if (timeOut <= 0 && timeOut != Timeout.Infinite)
            {
                throw new ArgumentOutOfRangeException(nameof(timeOut), "超时时间必须大于 0，或使用 Timeout.Infinite。 ");
            }
            if (maxFileBytes.HasValue && maxFileBytes.Value <= 0)
            {
                throw new ArgumentOutOfRangeException(nameof(maxFileBytes),
                    "文件大小上限必须大于 0。");
            }
            if (maxFileBytes.HasValue && fileStream.CanSeek &&
                fileStream.Length - fileStream.Position > maxFileBytes.Value)
            {
                throw new InvalidDataException(
                    $"上传文件超过允许上限 {maxFileBytes.Value} 字节。");
            }

            T result = null;
            try
            {
                byte[] fileBytes;
                int fileLength;
                using (var memoryStream = new MemoryStream())
                {
                    var buffer = ArrayPool<byte>.Shared.Rent(81920);
                    try

View on GitHub (pinned to be573f6f94)