{"record":{"id":"880adc7d291f4655","repo":"unoplatform/uno","slug":"main-window-must-be-initialized-before-frame","errorCode":null,"errorMessage":"Main window must be initialized before Frame","messagePattern":"Main window must be initialized before Frame","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"src/SamplesApp/SamplesApp.Shared/App.xaml.cs","lineNumber":370,"sourceCode":"\t\t}\n\n\t\tpublic event EventHandler? MainWindowActivated;\n\n#if HAS_UNO && !HAS_UNO_WINUI\n\t\tprotected override void OnWindowCreated(global::Microsoft.UI.Xaml.WindowCreatedEventArgs args)\n\t\t{\n\t\t\tif (Current is null)\n\t\t\t{\n\t\t\t\tthrow new InvalidOperationException(\"The Window should be created later in the application lifecycle.\");\n\t\t\t}\n\t\t}\n#endif\n\n\t\tprivate void InitializeFrame(string? arguments = null)\n\t\t{\n\t\t\tif (_mainWindow is null)\n\t\t\t{\n\t\t\t\tthrow new InvalidOperationException(\"Main window must be initialized before Frame\");\n\t\t\t}\n\n\t\t\tvar rootFrame = _mainWindow.Content as Frame;\n\n\t\t\t// Do not repeat app initialization when the Window already has content,\n\t\t\t// just ensure that the window is active\n\t\t\tif (rootFrame is null)\n\t\t\t{\n\t\t\t\t// Create a Frame to act as the navigation context and navigate to the first page\n\t\t\t\trootFrame = new Frame();\n\n\t\t\t\trootFrame.NavigationFailed += OnNavigationFailed;\n\n\t\t\t\t// Place the frame in the current Window\n\t\t\t\t_mainWindow.Content = rootFrame;\n\t\t\t}\n\n\t\t\tif (rootFrame.Content is null)","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/unoplatform/uno/blob/04183404888ea21b4e5bfa3493e8d5f15e972c3a/src/SamplesApp/SamplesApp.Shared/App.xaml.cs#L352-L388","documentation":"Thrown by InitializeFrame when the _mainWindow field is null. The method builds a Frame into the main window's content, so a null window means the app's initialization order skipped window creation before navigation setup.","triggerScenarios":"InitializeFrame invoked before EnsureWindowCreated / ActivateMainWindow has set _mainWindow — e.g. navigating during OnLaunched before the window was created, or a code path that calls InitializeFrame directly.","commonSituations":"Custom startup calling InitializeFrame early; window creation guarded by a condition that evaluated false; refactor that reordered EnsureWindowCreated after InitializeFrame; headless test harness that skips window creation.","solutions":["Ensure _mainWindow is created (call EnsureWindowCreated/Activate) before InitializeFrame.","In OnLaunched, follow the documented order: create window -> activate -> initialize frame.","Guard InitializeFrame to create the window if null rather than throw, if late initialization is intentional."],"exampleFix":"// before\nprivate void InitializeFrame(string? arguments = null)\n{\n    if (_mainWindow is null)\n        throw new InvalidOperationException(\"Main window must be initialized before Frame\");\n// after - ensure the window exists first\nprivate void InitializeFrame(string? arguments = null)\n{\n    _mainWindow ??= EnsureWindowCreated();\n    _mainWindow.Activate();","handlingStrategy":"validation","validationCode":"_mainWindow ??= EnsureWindowCreated();\nif (_mainWindow is null) throw new InvalidOperationException(\"Window creation returned null.\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Follow the documented startup order: create window -> activate -> initialize frame.","Ensure EnsureWindowCreated is idempotent and called before navigation.","Guard InitializeFrame to lazily create the window if null."],"tags":["app-lifecycle","window","frame","navigation","startup","ordering"],"backgroundTag":null,"analyzedSha":"04183404888ea21b4e5bfa3493e8d5f15e972c3a","analyzedAt":"2026-08-13T21:08:11.651Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}