lepoco/wpfui · error · InvalidOperationException

Use {nameof(CreateIconElement)}

Error message

Use {nameof(CreateIconElement)}

What it means

Thrown by IconSourceElement.InitializeChildren, which is invoked by IconElement.EnsureLayoutRoot during measure/arrange. IconSourceElement deliberately does not render children itself — it is a source wrapper whose only valid output path is CreateIconElement(), which materializes the inner IconSource into a real IconElement. The throw is a usage error marker: someone placed an IconSourceElement into the visual tree directly instead of using it as an Icon property value.

Source

Thrown at src/Wpf.Ui/Controls/IconElement/IconSourceElement.cs:37

        nameof(IconSource),
        typeof(IconSource),
        typeof(IconSourceElement),
        new FrameworkPropertyMetadata(null)
    );

    /// <summary>
    /// Gets or sets <see cref="IconSource"/>
    /// </summary>
    public IconSource? IconSource
    {
        get => (IconSource?)GetValue(IconSourceProperty);
        set => SetValue(IconSourceProperty, value);
    }

    protected override UIElement InitializeChildren()
    {
        // TODO: Come up with an elegant solution
        throw new InvalidOperationException($"Use {nameof(CreateIconElement)}");
    }

    public IconElement? CreateIconElement()
    {
        return IconSource?.CreateIconElement();
    }
}

View on GitHub (pinned to ffebacd610)

Solutions

1. Use IconSourceElement only as the value of an Icon dependency property — it will be coerced via CreateIconElement.
2. If you need a visual icon, assign an IconSourceElement.IconSource or use a concrete IconElement directly.
3. Do not add IconSourceElement to Children collections of panels.
4. In bindings, ensure the target property is an Icon property, not Content/Child.

Example fix

<!-- before -->
<StackPanel>
  <ui:IconSourceElement IconSource="..."/> <!-- measured -> throws -->
</StackPanel>

<!-- after -->
<ui:Button>
  <ui:Button.Icon>
    <ui:IconSourceElement IconSource="..."/>
  </ui:Button.Icon>
</ui:Button>

// Never place IconSourceElement in a panel's Children.
// Only assign it to an Icon dependency property:
button.Icon = new IconSourceElement { IconSource = source };

static bool IsAssignableToIconProperty(object? v) => v is null or IconElement or IconSourceElement;

When it happens

Trigger: Putting an <ui:IconSourceElement> directly into a panel/grid's children so WPF measures and arranges it; or subclassing and calling InitializeChildren manually. The coerce path (CreateIconElement) is bypassed because the element is treated as a standalone control rather than as an icon source.

Common situations: Confusing IconSource (data) with an icon control (visual); XAML that nests IconSourceElement as a child element of a layout panel instead of assigning it to an Icon property; binding a ContentControl's Content to an IconSourceElement.

Related errors

• IconElement should have only 1 child
• Expected either '{typeof(IconSourceElement)}' or '{typeof(Ic
• Window is null
• Unable to find the base directory of the application.
• ExceptionEnumToBooleanConverterParameterMustBeAnEnumName

AI-assisted analysis of lepoco/wpfui@ffebacd610 (2026-08-13). Data as JSON: /api/errors/14072920bf640080. Report an issue: GitHub.