stride3d/stride · error · YamlException

Unable to decode url reference

Error message

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

What it means

UrlReferenceSerializer.ConvertFrom deserializes UrlReference objects from YAML scalars of the form 'GUID:LOCATION' via AssetReference.TryParse. If the scalar does not contain a valid GUID followed by a colon and a location, deserialization aborts with this YamlException.

Solutions

Rewrite the scalar as GUID:LOCATION using the referenced asset's identifier (e.g. '6c9a4b1e-...:myFolder/myTexture.png')
Get the correct GUID from the asset's meta/YAML in the same project
If only a plain URL is intended, use the appropriate non-reference field type instead of UrlReference
Re-link the reference in the Stride editor and re-save the asset

Example fix

// before
Url: myTexture.png
// after
Url: 8f2a5c3e-1b4d-4a9c-b7e0-3d6f8a2c5e91:myTexture.png

Defensive patterns

Strategy: validation

Validate before calling

if (AssetReference.TryParse(text, out var guid, out var location)) { proceed(guid, location); } else { report(text); }

Type guard

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

Try / catch

try { LoadAsset(yaml); } catch (YamlException ex) when (ex.Message.Contains("Unable to decode url reference")) { log.Error($"Bad URL reference: {ex.Message}"); throw; }

Prevention

Always write references as GUID:LOCATION pairs
Link references through the Stride editor instead of hand-editing
Validate reference format in CI with AssetReference.TryParse

When it happens

Trigger: Deserializing a YAML asset where a UrlReference-typed field contains a scalar missing the GUID part, missing the ':' separator, containing an invalid GUID, or an empty/whitespace value.

Common situations: Hand-editing asset YAML references; scripts writing URLs instead of GUID:LOCATION references; bad merges dropping the GUID portion; referencing an asset that was never saved (no GUID assigned).

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 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/ff9c6d2c9b7be0c1. Report an issue: GitHub.

Appendix: source

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

namespace Stride.Core.Assets.Serializers;

/// <summary>
/// A Yaml serializer for <see cref="UrlReference"/>
/// </summary>
[YamlSerializerFactory(YamlAssetProfile.Name)]
internal class UrlReferenceSerializer : AssetScalarSerializerBase
{
    public override bool CanVisit(Type type)
    {
        return UrlReferenceBase.IsUrlReferenceType(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 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)