stride3d/stride · error · InvalidOperationException

MipLevels must be <=

Error message

MipLevels must be <= {maxMips}

What it means

Image.CalculateMipLevels(width, mipLevels) computes the mip chain length for a 1D image. When an explicit MipMapCount greater than 1 is requested, it must not exceed CountMips(width); otherwise an InvalidOperationException is thrown because the requested chain cannot be built from the given width.

Solutions

  1. Use MipMapCount.Auto (0) so the maximum valid chain is computed automatically
  2. Compute CountMips(width) first and clamp the requested count to it
  3. Increase the image width if more mip levels are genuinely required

Example fix

// before
int mips = Image.CalculateMipLevels(16, 10);
// after
int mips = Image.CalculateMipLevels(16, MipMapCount.Auto);
Defensive patterns

Strategy: validation

Validate before calling

int max = Image.CountMips(width);
if (requestedMips > max) requestedMips = MipMapCount.Auto; // or clamp to max
int mips = Image.CalculateMipLevels(width, requestedMips);

Type guard

bool IsValidMipCount(int width, MipMapCount mips) => mips <= 1 || mips <= Image.CountMips(width);

Try / catch

try { int mips = Image.CalculateMipLevels(width, count); }
catch (InvalidOperationException) { mips = Image.CalculateMipLevels(width, MipMapCount.Auto); }

Prevention

When it happens

Trigger: Calling CalculateMipLevels(width, mipLevels) with mipLevels > 1 and mipLevels > CountMips(width) — e.g. requesting 8 mip levels on a 16-pixel-wide image (max 5).

Common situations: Hardcoding mip counts (e.g. 10) from another texture size; loading mip data from a file whose chain does not match the declared width; generating mips for very small dimensions.

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

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/2a2cf1a47f38d86d. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Foundation/Graphics/Image.cs:622

        {
            ArgumentNullException.ThrowIfNull(imageStream);

            Save(PixelBuffers, PixelBuffers.Length, Description, imageStream, fileType);
        }

        /// <summary>
        /// Calculates the number of miplevels for a Texture 1D.
        /// </summary>
        /// <param name="width">The width of the texture.</param>
        /// <param name="mipLevels">A <see cref="MipMapCount"/>, set to true to calculates all mipmaps, to false to calculate only 1 miplevel, or > 1 to calculate a specific amount of levels.</param>
        /// <returns>The number of miplevels.</returns>
        public static int CalculateMipLevels(int width, MipMapCount mipLevels)
        {
            if (mipLevels > 1)
            {
                int maxMips = CountMips(width);
                if (mipLevels > maxMips)
                    throw new InvalidOperationException($"MipLevels must be <= {maxMips}");
            }
            else if (mipLevels == 0)
            {
                mipLevels = CountMips(width);
            }
            else
            {
                mipLevels = 1;
            }
            return mipLevels;
        }

        /// <summary>
        /// Calculates the number of miplevels for a Texture 2D.
        /// </summary>
        /// <param name="width">The width of the texture.</param>
        /// <param name="height">The height of the texture.</param>
        /// <param name="mipLevels">A <see cref="MipMapCount"/>, set to true to calculates all mipmaps, to false to calculate only 1 miplevel, or > 1 to calculate a specific amount of levels.</param>

View on GitHub (pinned to 96fad776d2)