{"record":{"id":"2794b846ee2c1efd","repo":"AvaloniaUI/Avalonia","slug":"could-not-get-platform-handle","errorCode":null,"errorMessage":"Could not get platform handle","messagePattern":"Could not get platform handle","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"samples/IntegrationTestApp/Pages/EmbeddingPage.axaml.cs","lineNumber":85,"sourceCode":"        root.Prepare();\n\n        var window = new NSWindow(\n            new CGRect(0, 0, root.Width, root.Height),\n            NSWindowStyle.Titled | NSWindowStyle.Closable,\n            NSBackingStore.Buffered,\n            false);\n\n        window.Identifier = \"ModalNativeWindow\";\n        window.WillClose += (_, _) => NSApplication.SharedApplication.StopModal();\n\n        button.Click += (_, _) =>\n        {\n            ModalResultTextBox.Text = \"Clicked\";\n            window.Close();\n        };\n\n        if (root.TryGetPlatformHandle() is not { } handle)\n            throw new InvalidOperationException(\"Could not get platform handle\");\n\n        window.ContentView = (NSView)Runtime.GetNSObject(handle.Handle)!;\n        root.StartRendering();\n\n        return window;\n    }\n}\n","sourceCodeStart":67,"sourceCodeEnd":93,"githubUrl":"https://github.com/AvaloniaUI/Avalonia/blob/11c542726898ae954a1ef668c65ec79ec92ab17d/samples/IntegrationTestApp/Pages/EmbeddingPage.axaml.cs#L67-L93","documentation":"In the macOS embedding test app, an Avalonia NativeControlHost root needs a real NSView handle. TryGetPlatformHandle returns null when the underlying AvaloniaView has not yet produced a platform surface. The InvalidOperationException means the embeddable view is not yet realized/attached, so there is no NSView to hand to the native window.","triggerScenarios":"Calling TryGetPlatformHandle() on a NativeControlHost root that has not been attached/realized to a TopLevel (no platform backend created yet), typically during early init or before the view is added to the visual tree.","commonSituations":"Invoking the embedding code path before the Avalonia application/window is fully initialized; calling on a headless or detached view; macOS-specific path where the NSView is created lazily on first render.","solutions":["Defer embedding until the view is attached and its TopLevel platform handle exists (e.g. in a Loaded/AttachedToVisualTree handler).","Guard with `if (root.TryGetPlatformHandle() is { } handle)` and skip or retry rather than throwing during early init.","Ensure an Avalonia macOS app lifecycle (UseMacOS()) is running so the platform surface is created.","Verify the NativeControlHost root is actually part of a realized TopLevel before calling."],"exampleFix":"// before\nif (root.TryGetPlatformHandle() is not { } handle)\n    throw new InvalidOperationException(\"Could not get platform handle\");\n\n// after (defer / guard instead of throwing)\nif (root.TryGetPlatformHandle() is not { } handle)\n{\n    // not realized yet; retry on attach\n    root.AttachedToVisualTree += (_, _) => AttachNativeWindow(root);\n    return;\n}","handlingStrategy":"type-guard","validationCode":"// only embed when a real handle exists\nif (root.TryGetPlatformHandle() is not { } handle) return;","typeGuard":"static bool HasPlatformHandle(INativeControlHostImplRoot r) => r.TryGetPlatformHandle() is not null;","tryCatchPattern":"try { /* build window.ContentView */ }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"platform handle\"))\n{ /* defer to AttachedToVisualTree */ }","preventionTips":["Defer embedding until the view is attached/realized.","Subscribe to AttachedToVisualTree and retry.","Guard on TryGetPlatformHandle() instead of throwing during early init."],"tags":["macos","embedding","native-control-host","nsview","integration-test"],"backgroundTag":null,"analyzedSha":"11c542726898ae954a1ef668c65ec79ec92ab17d","analyzedAt":"2026-08-13T11:57:40.261Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}