dotnet/wpf · error · InvalidOperationException

SR.MustUseWindowStyleNone

Error message

SR.MustUseWindowStyleNone

What it means

Window.AllowsTransparency=true requires the window to be rendered by WPF itself with no non-client frame, so only WindowStyle.None is compatible. VerifyConsistencyWithAllowsTransparency throws InvalidOperationException when AllowsTransparency is true and the WindowStyle is SingleBorderWindow, ThreeDBorderWindow, or ToolWindow. The check runs when either property changes.

Solutions

  1. Set WindowStyle="None" whenever AllowsTransparency="True"
  2. If a border is still wanted, draw a custom chrome/border inside the borderless transparent window
  3. Alternatively drop AllowsTransparency if the standard window frame is required

Example fix

// before
<Window AllowsTransparency="True" WindowStyle="SingleBorderWindow" />
// after
<Window AllowsTransparency="True" WindowStyle="None" />
Defensive patterns

Strategy: validation

Validate before calling

if (window.AllowsTransparency && window.WindowStyle != WindowStyle.None) window.WindowStyle = WindowStyle.None;

Try / catch

try { window.AllowsTransparency = true; } catch (InvalidOperationException) { window.WindowStyle = WindowStyle.None; window.AllowsTransparency = true; }

Prevention

When it happens

Trigger: Setting WindowStyle="SingleBorderWindow" (or ToolWindow/ThreeDBorderWindow) together with AllowsTransparency="True" in XAML or code — in either order, since the consistency is verified on each change.

Common situations: Enabling transparency for a custom-chrome window but forgetting to also set WindowStyle="None", designer-generated XAML with conflicting attributes, migrating apps that turned on AllowsTransparency later.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/337e15843e729554. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Window.cs:6932

            if ((_hiddenWindow != null) && (_hiddenWindow.Handle == _ownerHandle))
            {
                SetOwnerHandle(IntPtr.Zero);
            }
        }

        private void VerifyConsistencyWithAllowsTransparency()
        {
            if (AllowsTransparency)
            {
                VerifyConsistencyWithAllowsTransparency(WindowStyle);
            }
        }

        private void VerifyConsistencyWithAllowsTransparency(WindowStyle style)
        {
            if (AllowsTransparency && style != WindowStyle.None)
            {
                throw new InvalidOperationException(SR.MustUseWindowStyleNone);
            }
        }

        private void VerifyConsistencyWithShowActivated()
        {
            //
            // We don't support to show a maximized non-activated window.
            // Don't check this consistency in a RBW (would break because Visibility is set when launching the RBW).
            //
            if (!_inTrustedSubWindow && WindowState == WindowState.Maximized && !ShowActivated)
                throw new InvalidOperationException(SR.ShowNonActivatedAndMaximized);
        }

        private static bool IsValidSizeToContent(SizeToContent value)
        {
            return value == SizeToContent.Manual ||
                   value == SizeToContent.Width ||
                   value == SizeToContent.Height ||

View on GitHub (pinned to 81131a70a4)