nopSolutions/nopCommerce · error · NopException

PackingPackageVolume exceeds max package size

Error message

PackingPackageVolume exceeds max package size

What it means

Thrown during package dimension calculation when the configured PackingPackageVolume (or its default of 5184 cubic inches) produces cube-root-derived dimensions whose combined girth+length exceeds the UPS size limit. The method computes a single dimension as the floor of the cube root, then checks GetPackageSize(dim, dim, dim) against GetSizeLimitAsync(). If the default or configured volume yields a package too large for UPS, this error fires.

Source

Thrown at src/Plugins/Nop.Plugin.Shipping.UPS/Services/UPSService.cs:662

            foreach (var item in shippingOptionRequest.Items)
            {
                //get dimensions and weight of the single item
                var (itemWidth, itemLength, itemHeight) = await GetDimensionsForSingleItemAsync(item.ShoppingCartItem, item.Product);

                totalVolume += item.GetQuantity() * itemWidth * itemLength * itemHeight;
            }
            
            if (totalVolume > decimal.Zero)
            {
                //use default value (in cubic inches) if not specified
                var packageVolume = _upsSettings.PackingPackageVolume;
                if (packageVolume <= 0)
                    packageVolume = 5184;

                //calculate cube root (floor)
                dimension = Convert.ToInt32(Math.Floor(Math.Pow(Convert.ToDouble(packageVolume), 1.0 / 3.0)));
                if (GetPackageSize(dimension, dimension, dimension) > await GetSizeLimitAsync())
                    throw new NopException("PackingPackageVolume exceeds max package size");

                //adjust package volume for dimensions calculated
                packageVolume = dimension * dimension * dimension;

                totalPackagesBySizeLimit = Convert.ToInt32(Math.Ceiling(totalVolume / packageVolume));
            }

            width = length = height = dimension;
        }

        //get total packages number according to package limits
        var weight = await GetWeightAsync(shippingOptionRequest);
        var weightLimit = await GetWeightLimitAsync();
        var totalPackagesByWeightLimit = weight > weightLimit
            ? Convert.ToInt32(Math.Ceiling(weight / weightLimit))
            : 1;
        var totalPackages = Math.Max(Math.Max(totalPackagesBySizeLimit, totalPackagesByWeightLimit), 1);

View on GitHub (pinned to 64bdf2ff08)

Solutions

  1. Reduce the PackingPackageVolume setting at Admin > Configuration > Shipping > UPS to a smaller value (e.g. try 1728 for 12-inch cubes)
  2. Verify the UPS DimensionsType setting (IN vs CM) — a CM-based volume in a setting expecting inches causes inflation
  3. Check GetSizeLimitAsync() return value and ensure it reflects current UPS limits for your account/service type
  4. Calculate the correct volume: if size limit is L, then max dimension = floor(L/3) and max volume = (floor(L/3))^3

Example fix

// before
// PackingPackageVolume = 5184 (default) → dimension 17 → size 51

// after — compute a safe volume from the size limit
var sizeLimit = await GetSizeLimitAsync(); // e.g. 165 inches
var maxDimension = Math.Floor(sizeLimit / 3.0);   // 55
var safeVolume = Math.Pow(maxDimension, 3);        // 166375
// or simply set PackingPackageVolume to a conservative value
_upsSettings.PackingPackageVolume = 1728; // 12-inch cube → size 36
Defensive patterns

Strategy: validation

Validate before calling

// Validate PackingPackageVolume against the size limit before shipping
var sizeLimit = await GetSizeLimitAsync();
var dimension = Convert.ToInt32(Math.Floor(Math.Pow(Convert.ToDouble(_upsSettings.PackingPackageVolume <= 0 ? 5184 : _upsSettings.PackingPackageVolume), 1.0 / 3.0)));
if (GetPackageSize(dimension, dimension, dimension) > sizeLimit)
    throw new InvalidOperationException($"PackingPackageVolume {_upsSettings.PackingPackageVolume} exceeds max package size {sizeLimit}");

Try / catch

// UPS errors throw directly; caller must catch
try
{
    var response = await _upsService.GetRatesAsync(request);
}
catch (NopException ex) when (ex.Message.Contains("PackingPackageVolume"))
{
    _logger.Error($"UPS PackingPackageVolume too large; reduce it in settings: {ex.Message}");
    return ErrorResult("Shipping calculation unavailable due to package configuration");
}

Prevention

When it happens

Trigger: PackingPackageVolume setting is set to a value whose cube root (floored) multiplied by 3 (length + 2*(width+height) or similar girth calculation) exceeds the UPS size limit returned by GetSizeLimitAsync. Even the default 5184 yields dimension 17, giving size 17+17+17=51 which could exceed limits in certain configurations.

Common situations: Administrator set PackingPackageVolume to an excessively large value; UPS changed size limits in a newer API version; the weight/dimension type settings (IN/CM) interact with the limit calculation producing unexpected results; default volume is too large for certain UPS service types with reduced limits.

Related errors

AI-assisted analysis of nopSolutions/nopCommerce@64bdf2ff08 (2026-08-13). Data as JSON: /api/errors/862b88c6fcaeb50f. Report an issue: GitHub.