stride3d/stride · error · NotSupportedException

Type [ ] is not supported. You must specify an explicit…

Error message

Type [{type.Name}] is not supported. You must specify an explicit PixelFormat

What it means

ConvertTypeToFormat maps a C# vertex type (float, Vector2, Color, etc.) to a default PixelFormat. If the type has no registered mapping, the library throws NotSupportedException telling the caller to supply an explicit PixelFormat when constructing the VertexElement.

Solutions

Pass an explicit PixelFormat, e.g. new VertexElement("POSITION", PixelFormat.R32G32B32_Float)
Change the vertex field to a supported type (float, Vector2/3/4, Color, etc.)

Example fix

// before
VertexElement.FromType<MyHalf4Type>("TANGENT") // format inference fails
// after
new VertexElement("TANGENT", 0, PixelFormat.R32G32B32A32_Float)

Defensive patterns

Strategy: validation

Validate before calling

var supported = new HashSet<Type> { typeof(float), typeof(Vector2), typeof(Vector3), typeof(Vector4), typeof(Color), typeof(byte), typeof(Half) };
bool FormatInferable(Type t) => supported.Contains(t);

Try / catch

try { element = VertexElement.FromType<T>(name); } catch (NotSupportedException) { element = new VertexElement(name, 0, explicitFormat); }

Prevention

Always pass an explicit PixelFormat for custom vertex types
Restrict vertex struct fields to types with built-in format inference
Map new vertex types to formats when introducing them

When it happens

Trigger: Creating a VertexElement from a custom struct type (e.g. a user-defined half-float struct or Half4 wrapper) without specifying a PixelFormat, so the library must infer the format and fails.

Common situations: Custom vertex structs with exotic types (Half, normalized byte vectors) that lack built-in format inference; refactoring a vertex type without updating the format mapping.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/VertexElement.cs:637

            if (typeof(Half) == type)
                return PixelFormat.R16_Float;

            if (typeof(Int4) == type)
                return PixelFormat.R32G32B32A32_UInt;
            if (typeof(Int3) == type)
                return PixelFormat.R32G32B32_UInt;
            if (typeof(int) == type)
                return PixelFormat.R32_UInt;
            if (typeof(uint) == type)
                return PixelFormat.R32_UInt;

            //if (typeof(Bool4) == typeT)
            //    return PixelFormat.R32G32B32A32_UInt;

            //if (typeof(Bool) == typeT)
            //    return PixelFormat.R32_UInt;

            throw new NotSupportedException($"Type [{type.Name}] is not supported. You must specify an explicit PixelFormat");
        }
    }

    #region Serializer

    /// <summary>
    ///   Provides functionality to serialize and deserialize <see cref="VertexElement"/> objects.
    /// </summary>
    internal class Serializer : DataSerializer<VertexElement>
    {
        /// <summary>
        ///   Serializes or deserializes a <see cref="VertexElement"/> object.
        /// </summary>
        /// <param name="vertexElement">The object to serialize or deserialize.</param>
        /// <inheritdoc/>
        public override void Serialize(ref VertexElement vertexElement, ArchiveMode mode, SerializationStream stream)
        {
            if (mode == ArchiveMode.Deserialize)

View on GitHub (pinned to 96fad776d2)