AvaloniaUI/Avalonia · error · ExpressionParseException

Unknown RelativeSource mode.

Error message

Unknown RelativeSource mode.

What it means

Thrown by ParseRelativeSource when the identifier following '$' does not match either 'self' or 'parent' — the only two supported RelativeSource modes in Avalonia's binding mini-language. The parser reads an identifier via ParseIdentifier and checks it against the two known modes; anything else falls through to the else branch.

Source

Thrown at src/Avalonia.Base/Data/Core/Parsers/BindingExpressionGrammar.cs:366

                        }
                    }
                    else
                    {
                        var reader = new CharacterReader(args[0].AsSpan());
                        (ancestorNamespace, ancestorType) = ParseTypeName(ref reader);
                        ancestorLevel = int.Parse(args[1]);
                    }
                }
                nodes.Add(new AncestorNode
                {
                    Namespace = ancestorNamespace,
                    TypeName = ancestorType,
                    Level = ancestorLevel
                });
            }
            else
            {
                throw new ExpressionParseException(r.Position, "Unknown RelativeSource mode.");
            }

            return State.AfterMember;
        }

        private static TypeName ParseTypeName(
#if NET7SDK
            scoped
#endif
            ref CharacterReader r)
        {
            ReadOnlySpan<char> ns, typeName;
            ns = ReadOnlySpan<char>.Empty;
            var typeNameOrNamespace = r.ParseIdentifier();

            if (!r.End && r.TakeIf(':'))
            {
                ns = typeNameOrNamespace;

View on GitHub (pinned to 11c5427268)

Solutions

1. Use '$self' to reference the control itself or '$parent' (optionally with '[Type;level]') to reference an ancestor.
2. For templated parent bindings, use '$parent[Control] or the TemplatedSource in compiled bindings instead of a WPF-style mode name.
3. Check that the mode keyword is lowercase — the comparison is case-sensitive.

Example fix

<!-- before: unsupported WPF-style mode -->
{Binding $templeft}

<!-- after: use supported mode -->
{Binding $parent[Control]}

// Validate RelativeSource mode keyword
static void ValidateRelativeSourceMode(string path)
{
    if (path.Contains('$'))
    {
        var match = System.Text.RegularExpressions.Regex.Match(path, @"\$([a-zA-Z]+)");
        if (match.Success)
        {
            var mode = match.Groups[1].Value;
            if (mode != "self" && mode != "parent")
                throw new ArgumentException(
                    $"Unknown RelativeSource mode '${mode}'. Supported: 'self', 'parent'");
        }
    }
}

try
{
    var binding = new Binding(path);
}
catch (ExpressionParseException ex) when (ex.Message.Contains("Unknown RelativeSource mode"))
{
    logger.LogError($"Unknown RelativeSource mode at column {ex.Column}: use '$self' or '$parent'");
}

When it happens

Trigger: Writing '$templeft', '$findAncestor', '$previousData', or any '$xxx' that is not exactly '$self' or '$parent'. The identifier is compared case-sensitively via SequenceEqual against 'self' and 'parent'.

Common situations: Coming from WPF where RelativeSource modes include 'FindAncestor', 'PreviousData', 'TemplatedParent', 'Self' — Avalonia only supports 'self' and 'parent'; misspelling 'self' or 'parent'; using a WPF RelativeSource mode name that Avalonia does not implement.

Related errors

• Too many arguments in RelativeSource syntax sugar
• Unexpected end of expression.
• Invalid attached property name.
• Attached Property name expected after '.'.
• Expected ')'.

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/c3e4e8af6351f329. Report an issue: GitHub.