stride3d/stride · error · YamlException

Unable to decode asset reference

Error message

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

What it means

AssetReferenceSerializer.ConvertFrom deserializes a YAML scalar into an AssetReference. The scalar must be in the 'GUID:LOCATION' form (e.g. '2b4c...:MyAsset'), which it validates via AssetReference.TryParse. When the scalar does not match that format, a YamlException is thrown pointing at the offending scalar range.

Solutions

Fix the YAML value to the full 'GUID:LOCATION' format, using the asset's actual ItemId and its project-relative location.
Re-export or resave the asset in the Stride editor so the reference is serialized correctly.
Run AssetReference.TryParse on suspect values in a validation pass before loading the asset to pinpoint bad entries.
Check git merge conflicts on the asset file — a partially merged reference line is a common corruption source.

Example fix

// before (YAML)
Reference: "MyAsset"

// after (YAML)
Reference: "10b4d2cb-987f-4c2f-a1a3-2d0e0a44a5c8:MyAsset"

Defensive patterns

Strategy: validation

Validate before calling

if (!AssetReference.TryParse(rawValue, out var id, out var location))
    Console.WriteLine($"Malformed asset reference: {rawValue}");

Type guard

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

Try / catch

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

Prevention

Never hand-edit asset reference YAML values
Run AssetReference.TryParse over references in a pre-load validation pass
Resolve git merge conflicts in asset files by re-saving in the editor
Generate references with tooling that emits GUID:LOCATION

When it happens

Trigger: Loading a YAML asset whose AssetReference field value is not 'GUID:LOCATION' — missing colon, missing guid, an empty value, or a location containing an unexpected separator layout; hand-editing asset files or importing them from other formats.

Common situations: Manual YAML edits that dropped the guid part; assets migrated from another engine with plain path references; a tool that serialized the reference with the wrong format; corrupted asset files after merge conflicts.

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

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

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/Serializers/AssetReferenceSerializer.cs:26

namespace Stride.Core.Assets.Serializers;

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

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

    public override string ConvertTo(ref ObjectContext objectContext)
    {
        var assetReference = (AssetReference)objectContext.Instance;
        return ReferenceSerializationHelper.FormatReference(ref objectContext, assetReference.Id, assetReference.Location);
    }
}

View on GitHub (pinned to 96fad776d2)