stride3d/stride · error · YamlException

Unable to deserialize reference

Error message

Unable to deserialize reference: [{fromScalar.Value}]

What it means

Thrown by IdentifiableObjectSerializer's nested IdentifiableObjectReferenceSerializer.ConvertFrom when a scalar meant to identify an object reference cannot be parsed via TryParse into an identifier. The serializer tracks object references by Guid during YAML asset deserialization; a malformed identifier stops deserialization with this YamlException.

Solutions

  1. Fix the reference scalar in the YAML to a valid identifier expected by TryParse
  2. Re-export/resave the asset with a compatible Stride version so references are rewritten in the current format
  3. Remove the broken reference entry and re-link the object in the editor
  4. Compare against a known-good asset file to see the expected reference format

Example fix

// before
Reference: someObject!!
// after
Reference: 6c9a4b1e-0f2d-4c8a-b3e5-9a1d7f02c456
Defensive patterns

Strategy: validation

Validate before calling

if (Guid.TryParse(referenceText, out _)) { deserialize(); } else { report(referenceText); }

Type guard

bool IsParsableObjectReference(string? s) => s != null && Guid.TryParse(s, out _);

Try / catch

try { DeserializeAsset(yaml); } catch (YamlException ex) when (ex.Message.Contains("Unable to deserialize reference")) { log.Warn($"Stale object reference: {ex.Message}"); }

Prevention

When it happens

Trigger: Deserializing a YAML asset containing an object reference scalar whose value fails IdentifiableObjectSerializer.TryParse (not a valid Guid/identifier). This happens when the reference text was hand-edited or written by an incompatible serializer version.

Common situations: Upgrading Stride and old assets reference objects with a changed identifier format; manual edits of object reference entries; corrupted or truncated asset files from VCS merges.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/Serializers/IdentifiableObjectSerializer.cs:80

    }

    private static bool TryParse(string text, out Guid identifier)
    {
        if (!text.StartsWith(Prefix, StringComparison.Ordinal))
        {
            identifier = Guid.Empty;
            return false;
        }
        return Guid.TryParse(text.AsSpan(Prefix.Length), out identifier);
    }

    private class IdentifiableObjectReferenceSerializer : ScalarSerializerBase
    {
        public override object ConvertFrom(ref ObjectContext context, Scalar fromScalar)
        {
            if (!TryParse(fromScalar.Value, out var identifier))
            {
                throw new YamlException($"Unable to deserialize reference: [{fromScalar.Value}]");
            }

            // Add the path to the currently deserialized object to the list of object references
            if (!context.SerializerContext.Properties.TryGetValue(AssetObjectSerializerBackend.ObjectReferencesKey, out var objectReferences))
            {
                objectReferences = new YamlAssetMetadata<Guid>();
                context.SerializerContext.Properties.Add(AssetObjectSerializerBackend.ObjectReferencesKey, objectReferences);
            }
            var path = AssetObjectSerializerBackend.GetCurrentPath(ref context, true);
            objectReferences.Set(path, identifier);

            // Return default(T)
            //return !context.Descriptor.Type.IsValueType ? null : Activator.CreateInstance(context.Descriptor.Type);
            // Return temporary proxy instance
            var proxy = AbstractObjectInstantiator.CreateConcreteInstance(context.Descriptor.Type);
            // Filtering out interface and abstracts here as they're using a proxy type which doesn't have Id implemented
            if (context.Descriptor.Type.IsInterface == false && context.Descriptor.Type.IsAbstract == false && proxy is IIdentifiable identifiable)
                identifiable.Id = identifier;

View on GitHub (pinned to 96fad776d2)