{"record":{"id":"25a1b51993a8c6a2","repo":"dotnet/wpf","slug":"the-dispatcherpriorityawaiter-is-invalid","errorCode":null,"errorMessage":"The DispatcherPriorityAwaiter is invalid.","messagePattern":"The DispatcherPriorityAwaiter is invalid\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Microsoft.DotNet.Wpf/src/WindowsBase/System/Windows/Threading/DispatcherPriorityAwaiter.cs","lineNumber":56,"sourceCode":"        }\n\n        /// <summary>\n        ///     This awaiter is just a proxy for queuing the continuations, it\n        ///     never completes itself, so it doesn't have any result.\n        /// </summary>\n        public void GetResult()\n        {\n        }\n\n        /// <summary>\n        ///     This is called with the continuation, which is simply queued to\n        ///     the Dispatcher at the priority specified to the constructor.\n        /// </summary>\n        public void OnCompleted(Action continuation)\n        {\n            if(_dispatcher == null)\n            {\n                throw new InvalidOperationException(SR.DispatcherPriorityAwaiterInvalid);\n            }\n            \n            _dispatcher.InvokeAsync(continuation, _priority);\n        }\n\n        private readonly Dispatcher _dispatcher;\n        private readonly DispatcherPriority _priority;\n}\n}\n\n","sourceCodeStart":38,"sourceCodeEnd":67,"githubUrl":"https://github.com/dotnet/wpf/blob/81131a70a4c573cd62748a5c36908fc4d662daa9/src/Microsoft.DotNet.Wpf/src/WindowsBase/System/Windows/Threading/DispatcherPriorityAwaiter.cs#L38-L67","documentation":"DispatcherPriorityAwaitable's awaiter (OnCompleted) throws InvalidOperationException if the underlying _dispatcher is null. This happens when the awaiter instance was created through a default/invalid path rather than via Dispatcher.InvokeAsync or BeginInvoke, so there is no dispatcher to post the continuation to.","triggerScenarios":"Awaiting a DispatcherPriorityAwaitable obtained outside the supported API surface, or awaiting the same awaiter twice after it was reset/default-constructed (internal _dispatcher field null).","commonSituations":"Misusing Dispatcher.Yield or a default(DispatcherPriorityAwaitable)-style path, or caching/reusing an awaiter across awaits in custom async helpers.","solutions":["Obtain the awaiter only from Dispatcher.InvokeAsync(...).Task.GetAwaiter() or Dispatcher.Yield(priority) - never construct/default it yourself","Await the awaitable exactly once; create a new one for each yield point","Verify the code path sets a valid Dispatcher before OnCompleted is invoked if implementing a custom awaitable","Refactor to plain Task.Yield() plus InvokeAsync if the custom priority-yield is not strictly needed"],"exampleFix":"// before\nvar awaiter = default(DispatcherPriorityAwaitable).GetAwaiter();\nawait awaiter; // throws: invalid awaiter\n// after\nawait Dispatcher.Yield(DispatcherPriority.Background);","handlingStrategy":"validation","validationCode":"// Only obtain awaiters via supported APIs:\nvar awaitable = Dispatcher.Yield(DispatcherPriority.Background); // not default(...)","typeGuard":"bool isValidAwaiter(DispatcherPriorityAwaiter a) => a is not null; // default-constructed awaiters are invalid\n// prefer: never construct/default the awaiter yourself","tryCatchPattern":"try\n{\n    await dispatcherYieldAwaitable;\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"DispatcherPriorityAwaiter is invalid\"))\n{\n    // fix the awaitable source; do not retry the same invalid awaiter\n}","preventionTips":["Await Dispatcher.Yield()/InvokeAsync results only; never default-construct awaiters","Await each awaitable exactly once","Do not cache awaiter instances across awaits","Use Task.Yield() when custom priority is unnecessary"],"tags":["async","await","dispatcher","wpf"],"backgroundTag":"invalid-argument-value","analyzedSha":"81131a70a4c573cd62748a5c36908fc4d662daa9","analyzedAt":"2026-09-14T10:12:48.479Z","contentChangedAt":"2026-09-14T10:12:48.479Z","schemaVersion":2},"datasetVersion":"2026-09-21T21:30:21.729Z"}