stride3d/stride · error · InvalidOperationException

Error when creating the material

Error message

Error when creating the material [{0}]

What it means

Material.New generates the material compose from its descriptor on the graphics device. If any material feature/attribute reports errors during MaterialGenerator.Generate, the composed result has HasErrors set and New throws InvalidOperationException containing the composed error text.

Solutions

  1. Read the formatted error text in the exception (result.ToText()) to find which material feature/attribute failed
  2. Fix the offending MaterialDescriptor: repair missing shader references or remove the failing attribute
  3. Verify all shaders referenced by the material features compile and exist in the project
  4. Ensure the material's requirements are compatible with GraphicsProfileLevel of the target device
  5. Test the material in the editor (Game Studio) to see the generation errors before runtime

Example fix

// before: material with a custom attribute pointing to a deleted shader
var material = Material.New(device, brokenDescriptor);
// after: validate shader references exist first
if (!assetManager.Exists(customAttribute.ShaderSource))
    customAttribute = fallbackAttribute;
var material = Material.New(device, descriptor);
Defensive patterns

Strategy: try-catch

Validate before calling

// validate descriptor shaders exist before Material.New
foreach (var attr in descriptor.Attributes.OfType<ShaderMaterialAttribute>())
    if (!assetManager.Exists(attr.ShaderSource)) throw new InvalidOperationException($"Missing shader {attr.ShaderSource}");

Try / catch

try { material = Material.New(device, descriptor); }
catch (InvalidOperationException ex)
{
    logger.LogError(ex, "Material generation failed: {Details}", ex.Message);
    material = fallbackMaterial;
}

Prevention

When it happens

Trigger: Calling Material.New with a MaterialDescriptor whose features produce generation errors — e.g. incompatible attributes, missing shaders, unsupported graphics profile features — so MaterialGenerator returns a result with HasErrors == true.

Common situations: Custom material attributes referencing missing shader classes; material features unsupported by the device's requested graphics profile; broken asset references in a material descriptor after reorganization.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Rendering/Rendering/Material.cs:72

        /// <returns>An instance of a <see cref="Material"/>.</returns>
        /// <exception cref="System.ArgumentNullException">descriptor</exception>
        /// <exception cref="System.InvalidOperationException">If an error occurs with the material description</exception>
        public static Material New(GraphicsDevice device, MaterialDescriptor descriptor, ContentManager content = null)
        {
            if (descriptor == null) throw new ArgumentNullException("descriptor");

            // The descriptor is not assigned to the material because
            // 1) we don't know whether it will mutate and be used to generate another material
            // 2) we don't wanna hold on to memory we actually don't need
            var context = new MaterialGeneratorContext(new Material(), device)
            {
                GraphicsProfile = device.Features.RequestedProfile,
            };
            var result = MaterialGenerator.Generate(descriptor, context, string.Format("{0}:RuntimeMaterial", descriptor.MaterialId));

            if (result.HasErrors)
            {
                throw new InvalidOperationException(string.Format("Error when creating the material [{0}]", result.ToText()));
            }

            var material = result.Material;

            // A material feature can attach references to content instead of loaded objects (such as the
            // lookup table of the default specular model), and only a content load resolves those.
            // The generator runs outside of one, so the references are loaded here.
            foreach (var pass in material.Passes)
            {
                pass.Parameters.ResolveAttachedReferences(content, Log);
            }

            return material;
        }
    }
}

View on GitHub (pinned to 96fad776d2)