stride3d/stride · error · YamlException

Unable to find registered ParameterKey

Error message

Unable to find registered ParameterKey [{0}]

What it means

ParameterKeySerializer.ConvertFrom resolves a YAML scalar to a ParameterKey via ParameterKeys.FindByName. If no key with that name is registered in the global ParameterKey registry, a YamlException is thrown. It means the referenced key was never registered (assembly not loaded) or is misspelled in the asset.

Solutions

  1. Fix the key name in the asset YAML to exactly match a registered ParameterKey.
  2. Ensure the assembly defining the ParameterKey is referenced and scanned (ParameterKeys.FindByName registry).
  3. Rebuild assets after any rename of parameter keys so the cached YAML is regenerated.

Example fix

// before (asset yaml)
key: MyShaders.OldKeyName

// after (match the registered key)
key: MyShaders.ActualKeyName
Defensive patterns

Strategy: validation

Validate before calling

if (ParameterKeys.FindByName(keyName) == null)
    throw new ArgumentException($"Unknown ParameterKey '{keyName}'");

Try / catch

// catch YamlException from asset loading and report the offending key name
catch (YamlException ex) { log.Error($"ParameterKey not registered: {ex.Message}"); }

Prevention

When it happens

Trigger: Deserializing a YAML asset that references a shader/parameter key name which is not present in the registry at that moment; e.g. a stale key name after renaming a ParameterKey in code, or a plugin/assembly containing the key not being loaded.

Common situations: Renaming or deleting a ParameterKey after assets referenced it; key defined in an assembly not referenced by the serializer's scan; typo in the asset's YAML value.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Assets/Serializers/ParameterKeySerializer.cs:29

namespace Stride.Assets.Serializers
{
    /// <summary>
    /// A Yaml serializer for <see cref="ParameterKey"/>
    /// </summary>
    [YamlSerializerFactory(YamlAssetProfile.Name)]
    internal class ParameterKeySerializer : AssetScalarSerializerBase
    {
        public override bool CanVisit(Type type)
        {
            return typeof(ParameterKey).IsAssignableFrom(type);
        }

        public override object ConvertFrom(ref ObjectContext objectContext, Scalar fromScalar)
        {
            var parameterKey = ParameterKeys.FindByName(fromScalar.Value);
            if (parameterKey == null)
            {
                throw new YamlException(fromScalar.Start, fromScalar.End, "Unable to find registered ParameterKey [{0}]".ToFormat(fromScalar.Value));
            }
            return parameterKey;
        }

        protected override void WriteScalar(ref ObjectContext objectContext, ScalarEventInfo scalar)
        {
            // TODO: if ParameterKey is written to an object, It will not serialized a tag
            scalar.Tag = null;
            scalar.IsPlainImplicit = true;
            base.WriteScalar(ref objectContext, scalar);
        }

        public override string ConvertTo(ref ObjectContext objectContext)
        {
            return ((ParameterKey)objectContext.Instance).Name;
        }
    }
}

View on GitHub (pinned to 96fad776d2)