stride3d/stride · error · NotSupportedException

Image format not supported

Error message

Image format not supported

What it means

Image.Load(stream, fileType) tries every registered loader/saver whose FileType matches the requested format; if none of the registered decoders can parse the stream (no delegate matched, or all attempted and failed to yield an image), it throws NotSupportedException('Image format not supported'). This means the container was registered but the payload could not be decoded, or the file's actual encoding is not supported by the built-in loader.

Solutions

1. Verify the stream actually contains the declared file type (check magic bytes)
2. Re-export the image in a standard variant (e.g. uncompressed or widely supported BCn DDS, baseline PNG)
3. Update Stride to a version whose DDS/image loaders support the specific format
4. Register a custom loader via Image.Register for the unsupported format

Example fix

// before
var image = Image.Load(stream, ImageFileType.Dds); // BC7 payload
// after
var image = Image.Load(stream, ImageFileType.Dds); // after re-exporting the DDS uncompressed

// verify magic bytes match the declared format before loading
byte[] head = new byte[4]; stream.Read(head, 0, 4); stream.Position = 0;
bool looksLikeDds = head[0]=='D' && head[1]=='D' && head[2]=='S' && head[3]==' ';

try { image = Image.Load(stream, fileType); }
catch (NotSupportedException ex) when (ex.Message == "Image format not supported")
{ // fall back to another format or re-export the asset
  stream.Position = 0; image = Image.Load(stream, ImageFileType.Dds); }

When it happens

Trigger: Image.Load(stream, ImageFileType.X) where the registered loader for X returns false/cannot parse the data — e.g. a DDS with an unsupported compression format or an exotic PNG variant; or the stream content does not match the declared file type.

Common situations: Loading game-engine DDS files with BC6H/BC7 or unusual variants; corrupted or truncated image files; passing a stream of the wrong format with an explicit fileType; image codecs added in newer engine versions not present in the installed one.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• This file format is not yet implemented.
• Invalid Z slice index
• MipLevels must be <= {maxMips}
• Width/Height/Depth must be power of 2
• Custom strides is not supported with packed PixelFormats

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

Appendix: source

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

        /// <returns></returns>
        /// <exception cref="NotSupportedException"></exception>
        private static Image Load(IntPtr dataPointer, int dataSize, bool makeACopy, GCHandle? handle, bool loadAsSRGB = true, AlphaLoadMode alphaLoadMode = AlphaLoadMode.Preserve)
        {
            foreach (var loadSaveDelegate in loadSaveDelegates)
            {
                if (loadSaveDelegate.Load != null)
                {
                    var image = loadSaveDelegate.Load(dataPointer, dataSize, makeACopy, handle, alphaLoadMode);
                    if (image != null)
                    {
                        if (loadAsSRGB)
                            image.ConvertFormatToSRgb();

                        return image;
                    }
                }
            }
            throw new NotSupportedException("Image format not supported");
        }

        /// <summary>
        /// Saves this instance to a stream.
        /// </summary>
        /// <param name="pixelBuffers">The buffers to save.</param>
        /// <param name="count">The number of buffers to save.</param>
        /// <param name="description">Global description of the buffer.</param>
        /// <param name="imageStream">The destination stream.</param>
        /// <param name="fileType">Specify the output format.</param>
        /// <remarks>This method support the following format: <c>dds, bmp, jpg, png, gif, tiff, wmp, tga</c>.</remarks>
        internal static void Save(PixelBuffer[] pixelBuffers, int count, ImageDescription description, Stream imageStream, ImageFileType fileType)
        {
            foreach (var loadSaveDelegate in loadSaveDelegates)
            {
                if (loadSaveDelegate.FileType == fileType)
                {
                    loadSaveDelegate.Save(pixelBuffers, count, description, imageStream);

View on GitHub (pinned to 96fad776d2)