What causes "Child styles must have a nesting selector." in AvaloniaUI/Avalonia?

Prefix the child selector with the nesting selector: in C# start with `s.Nesting()`, in AXAML start the Selector with `^`.

AvaloniaUI/Avalonia · error · InvalidOperationException

Child styles must have a nesting selector.

Error message

Child styles must have a nesting selector.

What it means

Thrown during ValidateNestingSelector when a child style's selector chain, walked back to its leftmost element, does not start with a NestingSelector (`^`). Avalonia requires nested styles to explicitly reference their parent via `^`, so an unanchored child selector is ambiguous and rejected. The leftmost selector is reached via MovePreviousOrParent; if it is null and not a NestingSelector, this fires.

Source

Thrown at src/Avalonia.Base/Styling/Selector.cs:130

        {
            var s = this;

            if (inControlTheme)
            {
                if (!s.InTemplate && s.IsCombinator)
                    throw new InvalidOperationException(
                        "ControlTheme style may not directly contain a child or descendent selector.");
                if (s is TemplateSelector && templateCount++ > 0)
                    throw new InvalidOperationException(
                        "ControlTemplate styles cannot contain multiple template selectors.");
            }

            var previous = s.MovePreviousOrParent();

            if (previous is null)
            {
                if (s is not NestingSelector)
                    throw new InvalidOperationException("Child styles must have a nesting selector.");
            }
            else
            {
                previous.ValidateNestingSelector(inControlTheme, templateCount);
            }
        }

        private static SelectorMatch MatchUntilCombinator(
            StyledElement control,
            Selector start,
            IStyle? parent,
            bool subscribe,
            out Selector? combinator)
        {
            combinator = null;

            var activators = new AndActivatorBuilder();
            var result = Match(control, start, parent, subscribe, ref activators, ref combinator);

View on GitHub (pinned to 11c5427268)

Solutions

Prefix the child selector with the nesting selector: in C# start with `s.Nesting()`, in AXAML start the Selector with `^`.
If the style is not meant to be nested, attach it to the top-level Styles collection instead of as a child.

Example fix

// before (child style missing ^)
parent.Children.Add(new Style(s => s.Class("foo")) { ... });

// after
parent.Children.Add(new Style(s => s.Nesting().Class("foo")) { ... });

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the child selector chain is left-anchored by a NestingSelector before parenting.
static bool StartsAtNesting(Selector? s)
{
    Selector? cur = s, prev;
    do { prev = cur; cur = cur?.MovePreviousOrParent(); } while (cur is not null);
    return prev is NestingSelector;
}

Prevention

Always begin nested style selectors with `^` (C#: s.Nesting()).
Visually verify the `^` prefix in AXAML nested styles.
Avoid parenting selector-less styles under selector-bearing parents.

When it happens

Trigger: Adding a Style with a selector that omits `^` as a child of another Style or ControlTheme, e.g. a child style whose selector is `.Class("foo")` instead of `^.Class("foo")`.

Common situations: Writing nested styles in AXAML and forgetting the `^` prefix; assuming the parent is implicitly prepended; programmatically building child selectors without calling Nesting().

Related errors

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