stride3d/stride · error · ArgumentException

The pixel format is not supported. Supported formats are …

Error message

The pixel format {format} is not supported. Supported formats are {PixelFormat.B8G8R8A8_UNorm}, {PixelFormat.B8G8R8A8_UNorm_SRgb}, {PixelFormat.R8G8B8A8_UNorm}, {PixelFormat.R8G8B8A8_UNorm_SRgb}, {PixelFormat.R8_UNorm}, and {PixelFormat.A8_UNorm}

What it means

StandardImageHelper.CreateImage only knows how to synthesize pixel data for a small fixed set of formats: B8G8R8A8_UNorm(_SRgb), R8G8B8A8_UNorm(_SRgb), R8_UNorm, and A8_UNorm. Any other PixelFormat in the description falls through to a throw of ArgumentException naming the unsupported format and the full supported list.

Solutions

Change the image description's format to one of the supported list (prefer R8G8B8A8_UNorm).
Convert the source asset to an 8-bit RGBA/gray/alpha format before loading.
Use a loader that supports the target format (e.g. DDS-aware path) instead of StandardImageHelper.

Example fix

// before
description.Format = PixelFormat.R16G16B16A16_Float;
var img = image(description);
// after
description.Format = PixelFormat.R8G8B8A8_UNorm;
var img = image(description);

Defensive patterns

Strategy: validation

Validate before calling

static readonly PixelFormat[] Supported =
{
    PixelFormat.B8G8R8A8_UNorm, PixelFormat.B8G8R8A8_UNorm_SRgb,
    PixelFormat.R8G8B8A8_UNorm, PixelFormat.R8G8B8A8_UNorm_SRgb,
    PixelFormat.R8_UNorm, PixelFormat.A8_UNorm
};
if (!Supported.Contains(description.Format))
    throw new ArgumentException($"{description.Format} unsupported by StandardImageHelper");

Type guard

bool IsStandardHelperFormat(PixelFormat f) =>
    f == PixelFormat.B8G8R8A8_UNorm || f == PixelFormat.B8G8R8A8_UNorm_SRgb ||
    f == PixelFormat.R8G8B8A8_UNorm || f == PixelFormat.R8G8B8A8_UNorm_SRgb ||
    f == PixelFormat.R8_UNorm || f == PixelFormat.A8_UNorm;

Try / catch

try { img = image(description); }
catch (ArgumentException ex) when (ex.Message.Contains("pixel format")) { description.Format = PixelFormat.R8G8B8A8_UNorm; img = image(description); }

Prevention

Normalize all procedural/test image formats to R8G8B8A8_UNorm before calling the helper.
Keep the supported-format list checked against the helper version when upgrading Stride.
Route compressed/HDR formats to a loader that supports them.

When it happens

Trigger: Calling image(description) / StandardImageHelper.CreateImage with an ImageDescription whose Format is outside the supported set — e.g. R16G16B16A16_Float, BC-compressed, or 3-byte RGB formats.

Common situations: Procedurally generated or test images using float/half formats; loading DDS assets with block-compressed formats through the standard helper; changing a texture asset's format to HDR and rerunning the same load path.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Foundation/Graphics/StandardImageHelper.cs:105

                }
            }
        }
        else if (format is PixelFormat.R8_UNorm or PixelFormat.A8_UNorm)
        {
            // SpriteBatch only renders RGBA, so expand single-channel grey into RGB with opaque alpha.
            for (int y = 0; y < height; y++)
            {
                var srcRow = src + y * srcStride;
                for (int x = 0; x < width; x++)
                {
                    byte g = srcRow[x];
                    pixels[y * width + x] = new Rgba32(g, g, g, (byte)255);
                }
            }
        }
        else
        {
            throw new ArgumentException(
                $"The pixel format {format} is not supported. Supported formats are {PixelFormat.B8G8R8A8_UNorm}, {PixelFormat.B8G8R8A8_UNorm_SRgb}, {PixelFormat.R8G8B8A8_UNorm}, {PixelFormat.R8G8B8A8_UNorm_SRgb}, {PixelFormat.R8_UNorm}, and {PixelFormat.A8_UNorm}",
                nameof(description));
        }

        return SharpImage.LoadPixelData<Rgba32>(pixels, width, height);
    }


    /// <summary>
    ///   Copies a block of memory from a source buffer to a destination buffer,
    ///   converting each 32-bit pixel from RGBA to BGRA format.
    /// </summary>
    /// <param name="dest">A pointer to the destination buffer that will receive the converted BGRA pixel data.</param>
    /// <param name="src">A pointer to the source buffer containing the RGBA pixel data to copy and convert.</param>
    /// <param name="sizeInBytesToCopy">
    ///   The number of bytes to copy and convert. Must be a multiple of 4, as each pixel is represented by 4 bytes.
    /// </param>
    /// <exception cref="ArgumentException"><paramref name="sizeInBytesToCopy"/> is not a multiple of 4.</exception>

View on GitHub (pinned to 96fad776d2)