{"record":{"id":"19b18415cda658f5","repo":"MahApps/MahApps.Metro","slug":"overlaybox-can-not-be-founded-in-this-metrowindow","errorCode":null,"errorMessage":"OverlayBox can not be founded in this MetroWindow's template. Are you calling this before the window has loaded?","messagePattern":"OverlayBox can not be founded in this MetroWindow's template\\. Are you calling this before the window has loaded\\?","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/MahApps.Metro/Controls/MetroWindow.cs","lineNumber":978,"sourceCode":"            }\n\n            return (sb.Duration.HasTimeSpan && sb.Duration.TimeSpan.Ticks > 0)\n                   || (sb.AccelerationRatio > 0)\n                   || (sb.DecelerationRatio > 0)\n                   || (animation.Duration.HasTimeSpan && animation.Duration.TimeSpan.Ticks > 0)\n                   || animation.AccelerationRatio > 0\n                   || animation.DecelerationRatio > 0;\n        }\n\n        /// <summary>\n        /// Starts the overlay fade in effect.\n        /// </summary>\n        /// <returns>A task representing the process.</returns>\n        public async System.Threading.Tasks.Task ShowOverlayAsync()\n        {\n            if (this.overlayBox is null)\n            {\n                throw new InvalidOperationException(\"OverlayBox can not be founded in this MetroWindow's template. Are you calling this before the window has loaded?\");\n            }\n\n            if (this.IsOverlayVisible() && this.overlayStoryboard is null)\n            {\n                return;\n            }\n\n            this.Dispatcher.VerifyAccess();\n\n            var sb = this.OverlayFadeIn?.Clone();\n\n            if (!this.CanUseOverlayFadingStoryboard(sb, out var animation))\n            {\n                this.ShowOverlay();\n                return;\n            }\n\n            this.overlayStoryboard = sb;","sourceCodeStart":960,"sourceCodeEnd":996,"githubUrl":"https://github.com/MahApps/MahApps.Metro/blob/72099e310bac2d12ac98fd7560b69679252519f5/src/MahApps.Metro/Controls/MetroWindow.cs#L960-L996","documentation":"Thrown by MetroWindow.ShowOverlayAsync() when the internal overlayBox field (a Grid rendered behind dialogs) is null. The field is assigned during OnApplyTemplate, so calling the method before the window template has been applied/loaded means the control tree is not yet ready. This is a lifecycle/initialization-order error, not a configuration error.","triggerScenarios":"Calling ShowOverlayAsync() in the MetroWindow constructor, in the Loaded handler's early phase before OnApplyTemplate has run, or from a different thread before the window's visual tree is built. Also triggered when a custom window Style/ControlTemplate omits the 'PART_overlayBox' template part that the code-behind expects to find via GetTemplateChild.","commonSituations":"Developer calls await window.ShowOverlayAsync() right after constructing the window or inside the constructor. A custom MetroWindow style replaces the default template and forgets the overlay Grid named PART_overlayBox. Calling the overlay API from a background thread before the window has been shown.","solutions":["Move the ShowOverlayAsync() call into the window's Loaded event handler (after the template has been applied), not the constructor.","If using a custom ControlTemplate for MetroWindow, ensure it contains a Grid element named 'overlayBox' (PART) with appropriate panel ZIndex.","Check this.IsLoaded before calling the overlay API, and defer with Dispatcher.BeginInvoke if not yet loaded.","Do not call overlay methods from background threads; marshal to the UI thread first."],"exampleFix":"// before\npublic MyWindow()\n{\n    InitializeComponent();\n    this.ShowOverlayAsync(); // template not yet applied\n}\n\n// after\npublic MyWindow()\n{\n    InitializeComponent();\n    this.Loaded += async (_, _) => await this.ShowOverlayAsync();\n}","handlingStrategy":"validation","validationCode":"if (!window.IsLoaded)\n{\n    // defer until Loaded\n    window.Loaded += async (_, _) => await window.ShowOverlayAsync();\n    return;\n}\nawait window.ShowOverlayAsync();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never call ShowOverlayAsync from a MetroWindow constructor.","Use the Loaded event for first-time overlay calls.","If using a custom ControlTemplate, verify it contains the 'overlayBox' Grid part.","Avoid calling overlay APIs from background threads."],"tags":["wpf","mahapps","lifecycle","template","overlay","initialization"],"backgroundTag":null,"analyzedSha":"72099e310bac2d12ac98fd7560b69679252519f5","analyzedAt":"2026-08-13T20:19:34.419Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}