stride3d/stride · error · ArgumentOutOfRangeException

The Graphics Resource is a Texture, but its dimension is…

Error message

The Graphics Resource is a Texture, but its dimension is not one of the supported types.

What it means

When creating a texture on the fly for an update, the code maps the TextureDimension to D3D12 resource description fields. Dimensions outside the handled cases (Texture1D/2D/3D style cases) hit the default arm and throw ArgumentOutOfRangeException naming the texture parameter.

Solutions

  1. Set Texture.Dimension to a supported value (Texture1D, Texture2D, Texture3D) when creating the texture.
  2. Inspect how the texture was created — prefer Texture.New2D/New3D helpers that set valid dimensions.
  3. Verify data loading/serialization isn't corrupting the Dimension field.
  4. Patch the switch to add the missing dimension if the engine added new TextureDimension values.

Example fix

// before
var tex = new Texture { Width = 64, Height = 64 }; // Dimension left default
commandList.Update(tex, data);
// after
var tex = Texture.New2D(GraphicsDevice, 64, 64, PixelFormat.R8G8B8A8_UNorm, data);
Defensive patterns

Strategy: validation

Validate before calling

if (texture.Dimension is not TextureDimension.Texture1D
    and not TextureDimension.Texture2D
    and not TextureDimension.Texture3D)
    throw new ArgumentException("Unsupported texture dimension", nameof(texture));

Type guard

static bool HasSupportedDimension(Texture t) =>
    t.Dimension is TextureDimension.Texture1D or TextureDimension.Texture2D or TextureDimension.Texture3D;

Try / catch

try { commandList.Update(texture, data); }
catch (ArgumentOutOfRangeException ex) { log.Error("Texture dimension not supported for update", ex); }

Prevention

When it happens

Trigger: Calling Update on a Texture whose Dimension is not one of the supported values handled in the switch (e.g. an unusual/extended dimension or a corrupted default-constructed texture descriptor).

Common situations: Constructing a Texture manually without setting Dimension properly; porting textures with cube/array dimension combos not covered by this D3D12 code path; serialization bugs that produce invalid dimensions.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/Direct3D12/CommandList.Direct3D12.cs:2043

                    case TextureDimension.Texture2D:
                    case TextureDimension.TextureCube:
                        resourceDescription = texture.ConvertToNativeDescription2D();
                        resourceDescription.Width = (ulong) width;
                        resourceDescription.Height = (uint) height;
                        resourceDescription.DepthOrArraySize = 1;
                        resourceDescription.MipLevels = 1;
                        break;

                    case TextureDimension.Texture3D:
                        resourceDescription = texture.ConvertToNativeDescription3D();
                        resourceDescription.Width = (ulong) width;
                        resourceDescription.Height = (uint) height;
                        resourceDescription.DepthOrArraySize = (ushort) depth;
                        resourceDescription.MipLevels = 1;
                        break;

                    default:
                        throw new ArgumentOutOfRangeException(nameof(texture), "The Graphics Resource is a Texture, but its dimension is not one of the supported types.");
                }

                // TODO D3D12 allocate in upload heap (placed resources?)
                var heap = new HeapProperties
                {
                    CPUPageProperty = CpuPageProperty.WriteBack,
                    MemoryPoolPreference = MemoryPool.L0,
                    CreationNodeMask = 1,
                    VisibleNodeMask = 1,
                    Type = HeapType.Custom
                };

                HResult result = NativeDevice.CreateCommittedResource(in heap, HeapFlags.None,
                                                                      in resourceDescription, ResourceStates.GenericRead,
                                                                      pOptimizedClearValue: null,
                                                                      out ComPtr<ID3D12Resource> nativeUploadTexture);
                if (result.IsFailure)
                    result.Throw();

View on GitHub (pinned to 96fad776d2)