stride3d/stride · error · YamlException

Unable to decode asset part reference [{0}]. Expecting an EN

Error message

Unable to decode asset part reference [{0}]. Expecting an ENTITY_GUID

What it means

This error is thrown by IdentifiableAssetPartReferenceSerializer.ConvertFrom when a YAML scalar that should represent an asset part reference cannot be parsed as a Guid. Stride asset files (.sdfmt/.yaml) reference asset parts by their GUID; the serializer expects the scalar value to be a valid ENTITY_GUID string. If Guid.TryParse fails, the YAML deserialization of the asset part reference is aborted with this YamlException.

Solutions

1. Open the asset YAML at the reported line and replace the scalar with a valid entity GUID (32 hex digits or standard Guid string form)
2. If the referenced part no longer exists, remove the stale asset part reference entry from the YAML
3. Regenerate or re-save the asset in the Stride Game Studio so a correct GUID is written
4. Check for merge conflicts in the asset file and resolve by keeping one side's GUID, not a mixed value

Example fix

// before (in .sdfmt asset)
ReferencedPart: my-part-name
// after
ReferencedPart: 38a9a1a7-8e13-4b8f-9d10-2b62a4e5c001

if (Guid.TryParse(scalarValue, out var guid)) { /* proceed */ } else { /* fix or skip this reference */ }

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

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

When it happens

Trigger: Deserializing a Stride asset YAML where a scalar appears where an entity/asset-part GUID is expected, but the scalar is not parseable by Guid.TryParse (e.g. a name string, a relative path, an empty value, or a truncated GUID).

Common situations: Hand-editing .sdfmt asset files and mistyping a GUID; assets referencing parts whose GUID was corrupted by a bad merge, find/replace, or external tool; copy-pasting identifiers without the GUID portion.

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.

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

Related errors

• Unable to deserialize reference: [{fromScalar.Value}]
• Unable to decode url reference [{0}]. Expecting format GUID:
• Unable to load the given stream
• A part Id cannot be empty.
• The guid of the key does not match the guid of the value

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

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/Serializers/IdentifiableAssetPartReferenceSerializer.cs:22

using Stride.Core.Yaml;
using Stride.Core.Yaml.Events;
using Stride.Core.Yaml.Serialization;

namespace Stride.Core.Assets.Serializers;

[YamlSerializerFactory(YamlAssetProfile.Name)]
public sealed class IdentifiableAssetPartReferenceSerializer : ScalarOrObjectSerializer
{
    public override bool CanVisit(Type type)
    {
        return type == typeof(IdentifiableAssetPartReference);
    }

    public override object ConvertFrom(ref ObjectContext context, Scalar fromScalar)
    {
        if (!Guid.TryParse(fromScalar.Value, out var guid))
        {
            throw new YamlException(fromScalar.Start, fromScalar.End, "Unable to decode asset part reference [{0}]. Expecting an ENTITY_GUID".ToFormat(fromScalar.Value));
        }

        var result = context.Instance as IdentifiableAssetPartReference ?? (IdentifiableAssetPartReference)(context.Instance = new IdentifiableAssetPartReference());
        result.Id = guid;

        return result;
    }

    public override string ConvertTo(ref ObjectContext objectContext)
    {
        return ((IdentifiableAssetPartReference)objectContext.Instance).Id.ToString();
    }
}

View on GitHub (pinned to 96fad776d2)