lepoco/wpfui · error · InvalidOperationException

Cannot apply backdrop effect if ExtendsContentIntoTitleBar i

Error message

Cannot apply backdrop effect if ExtendsContentIntoTitleBar is false.

What it means

Thrown by FluentWindow.OnBackdropTypeChanged when the new backdrop type is anything other than None but ExtendsContentIntoTitleBar is false. Window backdrop effects (Mica, Acrylic, etc.) require the window's content to extend into the title bar area so the backdrop shows through; without that, the legacy title bar would occlude the effect. The library treats this as an invalid configuration rather than silently degrading.

Source

Thrown at src/Wpf.Ui/Controls/FluentWindow/FluentWindow.cs:244

            newValue = WindowBackdropType.None;
        }

        if (InteropHelper.Handle == IntPtr.Zero)
        {
            return;
        }

        SetWindowChrome();

        if (newValue == WindowBackdropType.None)
        {
            _ = WindowBackdrop.RemoveBackdrop(this);
            return;
        }

        if (!ExtendsContentIntoTitleBar)
        {
            throw new InvalidOperationException(
                $"Cannot apply backdrop effect if {nameof(ExtendsContentIntoTitleBar)} is false."
            );
        }

        if (WindowBackdrop.IsSupported(newValue) && WindowBackdrop.RemoveBackground(this))
        {
            _ = WindowBackdrop.ApplyBackdrop(this, newValue);

            _ = WindowBackdrop.RemoveTitlebarBackground(this);
        }
    }

    /// <summary>
    /// Private <see cref="ExtendsContentIntoTitleBar"/> property callback.
    /// </summary>
    private static void OnExtendsContentIntoTitleBarChanged(
        DependencyObject d,
        DependencyPropertyChangedEventArgs e

View on GitHub (pinned to ffebacd610)

Solutions

Set ExtendsContentIntoTitleBar = true before or together with the non-None WindowBackdropType.
In XAML, set both attributes on the FluentWindow: ExtendsContentIntoTitleBar="True" and WindowBackdropType="Mica".
If you genuinely want a standard title bar, keep WindowBackdropType = None.
When binding, sequence the view-model so IsExtendedContentIntoTitleBar is set first.

Example fix

<!-- before -->
<ui:FluentWindow WindowBackdropType="Mica"/> <!-- throws -->

<!-- after -->
<ui:FluentWindow ExtendsContentIntoTitleBar="True" WindowBackdropType="Mica"/>

Defensive patterns

Strategy: validation

Validate before calling

if (window.WindowBackdropType != WindowBackdropType.None && !window.ExtendsContentIntoTitleBar)
    throw new InvalidOperationException("Set ExtendsContentIntoTitleBar before backdrop.");

Prevention

Always pair WindowBackdropType with ExtendsContentIntoTitleBar="True" in XAML.
When binding backdrop type from a view-model, set the title-bar property first.
Keep WindowBackdropType = None if you need the standard title bar.

When it happens

Trigger: Setting WindowBackdropType to Mica/Acrylic/Tabbed (via property or OnBackdropTypeChanged) while ExtendsContentIntoTitleBar is false; binding the backdrop type to a value before enabling the extended title bar; applying a backdrop at construction where ExtendsContentIntoTitleBar defaults to false.

Common situations: Enabling Mica on a FluentWindow without setting ExtendsContentIntoTitleBar in XAML; toggling backdrop type from a view-model whose initial state does not also extend content; reading a 'how to enable Mica' guide that omitted the title-bar step.

Related errors

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