stride3d/stride · error · ArgumentException

Invalid mipmap level

Error message

Invalid mipmap level

What it means

Thrown by Image.GetPixelBuffer(arrayOrZSliceIndex, mipmap) when the requested mipmap level is greater than the texture's Description.MipLevels. Mipmap indices are zero-based and must stay below the declared mip count, so an out-of-range index indicates a caller bug or stale texture description.

Solutions

1. Clamp or loop with mip < image.Description.MipLevels
2. Compute the mip count from the texture dimensions (e.g. floor(log2(maxDim)) + 1) instead of hardcoding
3. If more mips are needed, recreate the image with a Description specifying the higher MipLevels

Example fix

// before
for (int mip = 0; mip <= image.Description.MipLevels; mip++)
    var pb = image.GetPixelBuffer(0, mip);
// after
for (int mip = 0; mip < image.Description.MipLevels; mip++)
    var pb = image.GetPixelBuffer(0, mip);

if (mip < 0 || mip >= image.Description.MipLevels)
    throw new ArgumentOutOfRangeException(nameof(mip), mip, $"Mip must be in [0,{image.Description.MipLevels})");

bool IsValidMip(Image image, int mip) => mip >= 0 && mip < image.Description.MipLevels;

try
{
    var pb = image.GetPixelBuffer(slice, mip);
}
catch (ArgumentException ex) when (ex.ParamName == "mipmap")
{
    log.Warn($"Mip {mip} unavailable (MipLevels={image.Description.MipLevels})");
    return null;
}

When it happens

Trigger: Calling image.GetPixelBuffer(0, mipmap) where mipmap >= Description.MipLevels, e.g. iterating mips with '<=' instead of '<', or reading mips from a reloaded image whose Description.MipLevels is smaller than expected.

Common situations: Looping over a hardcoded mip count (e.g. full chain of 12) while the image was loaded with a reduced chain; mismatch after resizing a texture so fewer mips are generated; code assuming mip levels from a different image instance.

Related errors

• Must be >= 0
• Invalid z slice index
• Invalid array slice index
• MipLevels must be <=
• Width/Height/Depth must be power of 2

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

Appendix: source

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

        /// <param name="mipmap">The mipmap.</param>
        /// <returns>A description of a particular mipmap for this texture.</returns>
        public MipMapDescription GetMipMapDescription(int mipmap)
        {
            return mipmapDescriptions[mipmap];
        }

        /// <summary>
        /// Gets the pixel buffer for the specified array/z slice and mipmap level.
        /// </summary>
        /// <param name="arrayOrZSliceIndex">For 3D image, the parameter is the Z slice, otherwise it is an index into the texture array.</param>
        /// <param name="mipmap">The mipmap.</param>
        /// <returns>A <see cref="Graphics.PixelBuffer"/>.</returns>
        /// <exception cref="ArgumentException">If arrayOrZSliceIndex or mipmap are out of range.</exception>
        public PixelBuffer GetPixelBuffer(int arrayOrZSliceIndex, int mipmap)
        {
            // Check for parameters, as it is easy to mess up things...
            if (mipmap > Description.MipLevels)
                throw new ArgumentException("Invalid mipmap level", nameof(mipmap));

            if (Description.Dimension == TextureDimension.Texture3D)
            {
                if (arrayOrZSliceIndex > Description.Depth)
                    throw new ArgumentException("Invalid z slice index", nameof(arrayOrZSliceIndex));

                // For 3D textures
                return GetPixelBufferUnsafe(0, arrayOrZSliceIndex, mipmap);
            }

            if (arrayOrZSliceIndex > Description.ArraySize)
            {
                throw new ArgumentException("Invalid array slice index", nameof(arrayOrZSliceIndex));
            }

            // For 1D, 2D textures
            return GetPixelBufferUnsafe(arrayOrZSliceIndex, 0, mipmap);
        }

View on GitHub (pinned to 96fad776d2)