stride3d/stride · error · ContentStreamingException

Texture streaming supports only 2D textures and 2D texture…

Error message

Texture streaming supports only 2D textures and 2D texture arrays.

What it means

StreamingTexture uploads mip data incrementally into 2D or 2D-array layouts; 3D textures (imageDescription.Depth != 1) are not supported by the streaming path. Init validates this up front and throws ContentStreamingException so unsupported 3D/volume textures never enter the streaming system with wrong assumptions (FullQualitySize, mip layout).

Solutions

1. Exclude the texture from streaming: register/load it as a regular (non-streaming) texture
2. If the texture is meant to be 2D, fix the source asset/import so Depth == 1 (a 2D array is still Depth==1 with a depth-slice count)
3. Downgrade to a 2D texture or bake the volume data into a 2D atlas before streaming

Example fix

// before
streamingManager.RegisterTexture(myVolumeTexture, myVolumeTexture.Description); // Depth > 1 -> throws
// after
if (description.Depth == 1)
    streamingManager.RegisterTexture(myTexture, description);
else
    // load as non-streaming texture
    var texture = myVolumeTexture;

if (imageDescription.Depth != 1)
    // register as non-streaming instead
    return; // regular Texture load path

bool IsStreamable(in ImageDescription d) => d.Depth == 1;

try
{
    streamingTexture.Init(provider, storage, ref description);
}
catch (ContentStreamingException)
{
    // load as regular texture
    texture = Content.Load<Texture>(url);
}

When it happens

Trigger: Calling StreamingTexture.Init (directly or via StreamingManager.RegisterTexture) with an ImageDescription whose Depth is greater than 1 — i.e. a 3D/volume texture or a texture asset flagged as streamable that is actually 3D.

Common situations: Volume/3D texture assets mistakenly marked for streaming; procedural textures created with depth > 1 and then registered with the StreamingManager; using texture formats/tools that emit 3D images into a pipeline configured for streaming.

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

• Missing content storage.
• Data chunk is missing.
• Data chunk has invalid size.
• Data chunk is not loaded.
• Reset is not supported by the asset tracker.

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

Appendix: source

Thrown at sources/engine/Stride.Rendering/Streaming/StreamingTexture.cs:184

            else
            {
                // Stream target quality in steps
                //requestedResidency = currentResidency - 1;

                // Stream target quality at once
                requestedResidency = targetResidency;
            }

            return requestedResidency;
        }

        /// <inheritdoc />
        internal override bool CanBeUpdated => textureToSync == null && base.CanBeUpdated;

        internal void Init(IDatabaseFileProviderService databaseFileProviderService, [NotNull] ContentStorage storage, ref ImageDescription imageDescription)
        {
            if (imageDescription.Depth != 1)
                throw new ContentStreamingException("Texture streaming supports only 2D textures and 2D texture arrays.", storage);

            Init(databaseFileProviderService, storage);
            texture.FullQualitySize = new Size3(imageDescription.Width, imageDescription.Height, imageDescription.Depth);
            description = imageDescription;
            residentMips = 0;
            CacheMipMaps();
        }

        /// <inheritdoc />
        internal override void FlushSync()
        {
            if (textureToSync == null)
                return;

            // register the new memory usage
            Manager.RegisterMemoryUsage(textureToSync.SizeInBytes - texture.SizeInBytes);

            // Texture is loaded and created in the async task.

View on GitHub (pinned to 96fad776d2)