lepoco/wpfui · error · InvalidOperationException

Use

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.

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

• Expected either ' ' or ' ' but got ' '.
• IconElement should have only 1 child
• Window is null
• Cannot apply backdrop effect if ExtendsContentIntoTitleBar…
• Cannot change DialogHostEx while the dialog is being shown.

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

Appendix: 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)