stride3d/stride · error · YamlException

Unable to extract url reference from object

Error message

Unable to extract url reference from object [{objectContext.Instance}]

What it means

UrlReferenceSerializer.ConvertTo serializes UrlReferenceBase instances back to 'GUID:LOCATION' scalars. If the object being serialized is not actually a UrlReferenceBase (pattern match fails), the serializer cannot extract Id and Url and throws this YamlException.

Solutions

Ensure the instance stored in the field is a UrlReferenceBase (e.g. UrlReference<T>) with valid Id and Url before saving
Fix code that assigns null or a different type to UrlReference-typed fields
If the value should be optional, make the property nullable and skip serialization for null
Debug the object at objectContext.Instance to see the actual runtime type

Example fix

// before
urlField = "myTexture.png";
// after
urlField = new UrlReference<Texture>(new Guid("8f2a5c3e-1b4d-4a9c-b7e0-3d6f8a2c5e91"), "myTexture.png");

Defensive patterns

Strategy: type-guard

Type guard

bool IsValidUrlReferenceObject(object? o) => o is UrlReferenceBase { Id: var id, Url: var url } && id != Guid.Empty && !string.IsNullOrEmpty(url);

Try / catch

try { ConvertTo(ref objectContext); } catch (YamlException ex) when (ex.Message.Contains("Unable to extract url reference")) { log.Error($"Instance is not UrlReferenceBase: {ex.Message}"); throw; }

Prevention

Check field types with pattern matching before saving objects containing UrlReferences
Never assign null or plain strings to UrlReference-typed members
Write unit tests that round-trip objects through the asset serializer

When it happens

Trigger: Serializing an object declared or cast as a UrlReference type whose runtime instance is not a UrlReferenceBase — e.g. a null instance, a wrong wrapper type assigned to the field, or a custom class deriving from something else stored in a UrlReference-typed slot.

Common situations: Custom serialization of objects with mistyped UrlReference fields; assigning null or a string to a UrlReference property before saving; bugs in generated or hand-written code that swaps field types during upgrades.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/Serializers/UrlReferenceSerializer.cs:39

    public override object ConvertFrom(ref ObjectContext context, Scalar fromScalar)
    {
        if (!AssetReference.TryParse(fromScalar.Value, out var guid, out var location))
        {
            throw new YamlException(fromScalar.Start, fromScalar.End, "Unable to decode url reference [{0}]. Expecting format GUID:LOCATION".ToFormat(fromScalar.Value));
        }

        return UrlReferenceBase.New(context.Descriptor.Type, guid, ReferenceSerializationHelper.RestoreLocation(ref context, location.FullPath));
    }

    public override string ConvertTo(ref ObjectContext objectContext)
    {
        if (objectContext.Instance is UrlReferenceBase urlReference)
        {
            return ReferenceSerializationHelper.FormatReference(ref objectContext, urlReference.Id, urlReference.Url);
        }

        throw new YamlException($"Unable to extract url reference from object [{objectContext.Instance}]");
    }
}

View on GitHub (pinned to 96fad776d2)