stride3d/stride · error · YamlException

Unable to decode asset reference

Error message

Unable to decode asset reference [{0}]. Expecting format GUID:LOCATION

What it means

ContentReferenceSerializer.ConvertFrom deserializes a YAML scalar into a proxy object for a content/asset reference (via AttachedReferenceManager.CreateProxyObject). Like the AssetReference serializer it requires the 'GUID:LOCATION' format, validated by AssetReference.TryParse, and throws YamlException with the scalar's source range when the format is wrong.

Solutions

1. Correct the YAML scalar to 'GUID:LOCATION' with the referenced content's ItemId and location.
2. Resave/re-export the referencing asset through the Stride editor to regenerate well-formed references.
3. Validate the raw string with AssetReference.TryParse before/during load to identify all malformed fields.
4. Compare with a known-good version of the asset file (git history) to restore the missing guid or location.

Example fix

// before (YAML)
Texture: "background.png"

// after (YAML)
Texture: "9f3a1c2e-11d2-4a55-b7aa-01c93f5e6d7b:background"

if (!AssetReference.TryParse(scalarValue, out var guid, out var location))
    Console.WriteLine($"Malformed content reference: {scalarValue}");

bool IsValidContentReference(string s) => AssetReference.TryParse(s, out _, out _);

try { return serializer.ConvertFrom(ref context, scalar); }
catch (YamlException ex) { log.Error($"Malformed content reference '{scalar.Value}' at {ex.Location}"); throw; }

When it happens

Trigger: Loading YAML containing a content-reference field whose value lacks the 'GUID:LOCATION' structure — no guid, no colon separator, empty scalar, or a URL-only reference; the field type does not match AssetReference.TryParse's expectations.

Common situations: Hand-edited or merge-conflicted asset files; references created by custom tooling that wrote only the URL; loading assets produced by an older or newer serialization format.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unable to decode asset reference
• Unable to extract asset reference from object
• Unable to extract url reference from object
• Event handlers can't be added or removed after the…
• RoutingSerializer expected in the chain of serializers

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

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/Serializers/ContentReferenceSerializer.cs:25

using Stride.Core.Yaml.Serialization;

namespace Stride.Core.Assets.Serializers;

[YamlSerializerFactory(YamlAssetProfile.Name)]
public class ContentReferenceSerializer : AssetScalarSerializerBase
{
    public static readonly ContentReferenceSerializer Default = new();

    public override bool CanVisit(Type type)
    {
        return AssetRegistry.IsExactContentType(type);
    }

    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 asset reference [{0}]. Expecting format GUID:LOCATION".ToFormat(fromScalar.Value));
        }

        var instance = AttachedReferenceManager.CreateProxyObject(context.Descriptor.Type, guid, ReferenceSerializationHelper.RestoreLocation(ref context, location.FullPath));
        return instance;
    }

    public override string ConvertTo(ref ObjectContext objectContext)
    {
        var attachedReference = AttachedReferenceManager.GetAttachedReference(objectContext.Instance)
            ?? throw new YamlException($"Unable to extract asset reference from object [{objectContext.Instance}]");
        return ReferenceSerializationHelper.FormatReference(ref objectContext, attachedReference.Id, attachedReference.Url);
    }
}

View on GitHub (pinned to 96fad776d2)