{"record":{"id":"f20ab7b003600529","repo":"dotnet/wpf","slug":"0-is-not-a-visual-or-visual3d","errorCode":null,"errorMessage":"'{0}' is not a Visual or Visual3D.","messagePattern":"'(.+?)' is not a Visual or Visual3D\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Microsoft.DotNet.Wpf/src/PresentationCore/MS/internal/Media/VisualTreeUtils.cs","lineNumber":219,"sourceCode":"        ///     Throws if the given element is not a Visual or Visual3D\n        ///     or if the Visual is on the wrong thread.\n        /// </summary>\n        private static void EnsureVisual(DependencyObject element, bool allowNull)\n        {\n            if (element == null)\n            {\n                if (!allowNull)\n                {\n                    throw new ArgumentNullException(nameof(element));\n                }\n\n                return;\n            }\n\n            // Would DTypes be faster?\n            if (!(element is Visual || element is Visual3D))\n            {\n                throw new ArgumentException(SR.Visual_NotAVisual);\n            }\n\n            element.VerifyAccess();            \n        }\n\n        /// <summary>\n        ///     Throws if the given element is null or not a visual type, otherwise\n        ///     either visual or visual3D will be non-null on exit.\n        /// </summary>\n        internal static void AsNonNullVisual(DependencyObject element, out Visual visual, out Visual3D visual3D)\n        {\n            ArgumentNullException.ThrowIfNull(element);\n\n            AsVisual(element, out visual, out visual3D);\n\n            Debug.Assert((visual == null) != (visual3D == null),\n                \"Either visual or visual3D exclusively should be non-null.\");\n        }","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/dotnet/wpf/blob/81131a70a4c573cd62748a5c36908fc4d662daa9/src/Microsoft.DotNet.Wpf/src/PresentationCore/MS/internal/Media/VisualTreeUtils.cs#L201-L237","documentation":"VisualTreeUtils.EnsureVisual throws ArgumentException ('{0}' is not a Visual or Visual3D.) when the supplied DependencyObject is neither a Visual nor a Visual3D, and then calls VerifyAccess to enforce thread affinity. The library requires all elements it manipulates to derive from the visual layer, not merely from DispatcherObject/DependencyObject.","triggerScenarios":"Passing a DependencyObject that is not a Visual — e.g. a freezable, a ResourceDictionary, a Binding expression, or a non-visual DependencyObject subclass — to an API guarded by EnsureNonNullVisual; also calling from a background thread (the subsequent VerifyAccess fails).","commonSituations":"Retrieving objects from Resources or code-behind fields typed as DependencyObject and assuming they are controls; passing Application-level or model objects; cross-thread access from a worker thread.","solutions":["Cast to Visual or Visual3D first and reject anything that fails the cast","Only pass elements that live in a visual tree (controls, panels, shapes)","Ensure the call runs on the object's owning UI thread"],"exampleFix":"// before\nVisualTreeUtils.EnsureNonNullVisual((DependencyObject)obj);\n// after\nif (obj is Visual || obj is Visual3D)\n{\n    VisualTreeUtils.EnsureNonNullVisual((DependencyObject)obj);\n}","handlingStrategy":"type-guard","validationCode":"bool isVisual = element is Visual || element is Visual3D;","typeGuard":"static bool IsVisualElement(DependencyObject d) => d is Visual || d is Visual3D;","tryCatchPattern":"try { VisualTreeUtils.EnsureNonNullVisual(element); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"not a Visual\")) { /* handle non-visual element */ }","preventionTips":["Type fields/parameters as Visual or UIElement instead of DependencyObject when a visual is required","Marshall calls to the UI thread (Dispatcher.Invoke) before visual-tree work","Don't pass resources/freezables where visuals are expected"],"tags":["type-mismatch","wpf","visual-tree"],"backgroundTag":"type-mismatch","analyzedSha":"81131a70a4c573cd62748a5c36908fc4d662daa9","analyzedAt":"2026-09-14T10:12:48.479Z","contentChangedAt":"2026-09-14T10:12:48.479Z","schemaVersion":2},"datasetVersion":"2026-09-22T01:17:13.364Z"}