What causes "Multi-dimensional arrays are not supported." in stride3d/stride?

Replace the multi-dimensional array with a jagged array (T[][]) in the model.

stride3d/stride · error · NotSupportedException

Multi-dimensional arrays are not supported.

Error message

Multi-dimensional arrays are not supported.

What it means

YamlAssemblyRegistry.DoGetShortAssemblyQualifiedName throws NotSupportedException when generating a short assembly-qualified type name for a multi-dimensional array (GetArrayRank() != 1). Only single-dimensional (possibly jagged) arrays are supported in the serialized type name format.

Solutions

Replace the multi-dimensional array with a jagged array (T[][]) in the model.
Replace with a single-dimensional array plus explicit width/height fields, reconstructing the grid on load.
Wrap the data in a serializable class (e.g. a Matrix/Grid type with rows as lists).
Serialize the flat data as int[] with dimension metadata.

Example fix

// before
public int[,] Grid { get; set; }
// after
public int[][] Grid { get; set; } // or store width/height + flat int[]

Defensive patterns

Strategy: type-guard

Validate before calling

static void AssertYamlSerializableShape(Type t) { if (t.IsArray && t.GetArrayRank() != 1) throw new NotSupportedException($"{t} is a multi-dimensional array; YAML serializer supports only single-dimensional arrays"); }

Type guard

static bool IsSupportedArrayType(Type t) => !t.IsArray || t.GetArrayRank() == 1;

Try / catch

try { serializer.Serialize(writer, graph); } catch (NotSupportedException ex) when (ex.Message.Contains("Multi-dimensional arrays")) { throw new NotSupportedException("Replace T[,] with T[][] or a wrapper class before YAML serialization", ex); }

Prevention

Avoid rectangular arrays (T[,]) in serializable models; use jagged arrays or wrapper classes.
Add a model audit that scans for GetArrayRank() != 1 before enabling YAML persistence.
Store grids as flat arrays plus dimension metadata.
Test serialize/deserialize round-trips for all model types.

When it happens

Trigger: Serializing a type such as int[,] or string[,,] where the serializer needs a short assembly-qualified name (e.g. emitting type tags or registering assemblies). Jagged arrays int[][] pass because their element types are traversed.

Common situations: Models containing rectangular 2D grids (matrices, tile maps) serialized to YAML for save files or asset pipelines; switching a property from int[][] to int[,] during refactoring; data-structure code ported from languages where multidimensional arrays are idiomatic.

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

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

Appendix: source

Thrown at sources/core/Stride.Core.Yaml/Serialization/YamlAssemblyRegistry.cs:446

            }
            if (genericArguments != null || arrayNesting > 0)
            {
                var genericType = shortAssemblyQualifiedName.Substring(0, firstBracket) + shortAssemblyQualifiedName.Substring(lastBracket + 1);
                return genericType;
            }
            return shortAssemblyQualifiedName;
        }

        private static void DoGetShortAssemblyQualifiedName(Type type, StringBuilder sb, bool appendAssemblyName = true)
        {
            // namespace
            sb.Append(type.Namespace).Append(".");
            // check if it's an array, store the information, and work on the element type
            var arrayNesting = 0;
            while (type.IsArray)
            {
                if (type.GetArrayRank() != 1)
                    throw new NotSupportedException("Multi-dimensional arrays are not supported.");
                type = type.GetElementType();
                ++arrayNesting;
            }
            // nested declaring types
            var declaringType = type.DeclaringType;
            if (declaringType != null)
            {
                var declaringTypeName = string.Empty;
                do
                {
                    declaringTypeName = declaringType.Name + "+" + declaringTypeName;
                    declaringType = declaringType.DeclaringType;
                } while (declaringType != null);
                sb.Append(declaringTypeName);
            }
            // type
            sb.Append(type.Name);
            // generic arguments

View on GitHub (pinned to 96fad776d2)