stride3d/stride · error · ArgumentOutOfRangeException

The region's width [ ] cannot be greater than the…

Error message

The region's width [{regionToCheck.Width}] cannot be greater than the mip-level's width [{width}]

What it means

Thrown by Texture upload/copy methods when a ResourceRegion's Width exceeds the mip-level's width. GPU textures are tightly sized per mip level, so a region larger than the mip cannot be addressed. The library validates regions up front with ArgumentOutOfRangeException before issuing the GPU copy.

Solutions

Compute the mip-level width (max(1, width >> mipLevel)) and clamp or resize the ResourceRegion to it.
Pass mipLevel 0 or a region derived from the actual mip dimensions.
Use the full texture (null region) if a sub-region is not needed.

Example fix

// before
var region = new ResourceRegion(0, 0, 0, textureWidth, textureHeight, 1);
texture.SetData(commandList, data, arrayIndex: 0, mipLevel: 2, region);
// after
int mipWidth = Math.Max(1, textureWidth >> 2);
int mipHeight = Math.Max(1, textureHeight >> 2);
var region = new ResourceRegion(0, 0, 0, mipWidth, mipHeight, 1);
texture.SetData(commandList, data, arrayIndex: 0, mipLevel: 2, region);

Defensive patterns

Strategy: validation

Validate before calling

int mipWidth = Math.Max(1, texture.Width >> mipLevel);
if (region != null && region.Width > mipWidth)
    throw new InvalidOperationException($"Region width {region.Width} exceeds mip {mipLevel} width {mipWidth}");

Try / catch

try { texture.SetData(cmd, data, arrayIndex, mipLevel, region); }
catch (ArgumentOutOfRangeException e) when (e.ParamName == "region") { log.Error("Texture region exceeds mip dimensions", e); }

Prevention

Always derive regions from the mip-level dimensions, never from the base resolution.
Use texture.Description.GetMipLevelDimensions(mipLevel) style helpers.
Prefer full-sub-resource updates (null region) unless partial updates are required.

When it happens

Trigger: Calling a Texture method (e.g. SetData with a region parameter) passing a ResourceRegion whose Width is greater than the width of the mip level selected by mipLevel, e.g. using mip-level-0 dimensions for a smaller mip.

Common situations: Uploading partial texture data while ignoring that mipLevel shrinks width; passing full-size regions to mip 2+; hard-coded region sizes that assumed a fixed resolution texture.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/Texture.cs:1465

        public unsafe void SetData<TData>(CommandList commandList, ReadOnlySpan<TData> fromData, int arrayIndex = 0, int mipLevel = 0, ResourceRegion? region = null) where TData : unmanaged
        {
            ArgumentNullException.ThrowIfNull(commandList);

            if (region.HasValue && Usage != GraphicsResourceUsage.Default)
                throw new ArgumentException($"A region can only be specified for Textures with {nameof(GraphicsResourceUsage)}.{nameof(GraphicsResourceUsage.Default)}", nameof(region));

            // Get a description for the specified mip-level
            ref readonly var mipmap = ref GetMipMapDescription(mipLevel);

            int width = mipmap.Width;
            int height = mipmap.Height;
            int depth = mipmap.Depth;

            // If we are using a region, then check that parameters are fine
            if (region is ResourceRegion regionToCheck)
            {
                if (regionToCheck.Width > width)
                    throw new ArgumentOutOfRangeException(nameof(region), $"The region's width [{regionToCheck.Width}] cannot be greater than the mip-level's width [{width}]");
                if (regionToCheck.Height > height)
                    throw new ArgumentOutOfRangeException(nameof(region), $"The region's height [{regionToCheck.Height}] cannot be greater than the mip-level's height [{height}]");
                if (regionToCheck.Depth > depth)
                    throw new ArgumentOutOfRangeException(nameof(region), $"The region's depth [{regionToCheck.Depth}] cannot be greater than the mip-level's depth [{depth}]");

                width = regionToCheck.Width;
                height = regionToCheck.Height;
                depth = regionToCheck.Depth;
            }

            var sizePerElement = Format.SizeInBytes;

            // Compute actual pitch
            Image.ComputePitch(Format, width, height, out var rowStride, out var textureDepthStride, out width, out height);

            // Size Of actual texture data
            int sizeOfTextureData = textureDepthStride * depth;

View on GitHub (pinned to 96fad776d2)