BackpressureMonitor.Dispose() deadlocks on single-threaded targets (Unity WebGL)

[ruslan-kodable]

Package

Sentry

.NET Flavor

IL2CPP

.NET Version

2.1 (Unity 2021.3.x)

OS

Browser

OS Version

Chrome 148.0.7778.97 (Official Build) (arm64) MacOS 26.4.1

Development Environment

Rider 2025.x (macOS)

Other Error Monitoring Solution

No

Other Error Monitoring Solution Name

No response

SDK Version

4.3.1

Self-Hosted Sentry Version

No response

Workload Versions

Unity 2021.3.24f1
emscripten (whatever ships with Unity 2021.3.x WebGL — 2.0.x range)
Build settings: IL2CPP, WebGL exception support ExplicitlyThrownExceptionsOnly, Brotli compression
react-unity-webgl v10 on the JS side (drives unityInstance.Quit())

UseSentry or SentrySdk.Init call

Auto-initialized via Sentry Unity's SentryOptions.asset ScriptableObject (the default Sentry Unity SDK init path — no manual SentrySdk.Init() call in user code). Options Configuration is wired to a SentryOptionsConfiguration : Sentry.Unity.SentryOptionsConfiguration subclass that sets options.EnableBackpressureHandling = false; inside #if UNITY_WEBGL && !UNITY_EDITOR — that one line is the workaround.

Steps to Reproduce

1. Create a Unity 2021.3.x project with Sentry Unity 4.x installed (default settings — EnableBackpressureHandling = true is the .NET 6.0 default).
2. Build for WebGL target.
3. Embed the build in a web page via react-unity-webgl (or any wrapper that calls unityInstance.Quit() on page navigation).
4. Load the page; let Unity fully initialize.
5. Trigger unityInstance.Quit() — e.g. press the browser Back button on a page that has a popstate listener wired to call Quit(), or close the tab, or navigate away programmatically.
6. Observe: the returned Quit() Promise never resolves; the Unity main loop never returns.

Expected Result

unityInstance.Quit() resolves; the page navigates cleanly.

Actual Result

The page wedges indefinitely. The tab appears frozen (no UI updates, the URL may have already updated in the address bar). The user must force-reload to recover. No exception is thrown, no Sentry event is emitted, no console error appears.

Root cause (analysis included for triage convenience, AI generated):

BackpressureMonitor.Dispose() in Internal/BackpressureMonitor.cs deadlocks on single-threaded platforms:

public void Dispose()
{
    try
    {
        _cts.Cancel();
        _workerTask.Wait();   // ← blocks main thread on WebGL
    }
    ...
}

The monitor's worker is started via Task.Run(() => DoWorkAsync(_cts.Token)) and loops on await Task.Delay(10s, ct).

On iOS/Android/Windows this works because Task.Run schedules on a real thread-pool worker. The main thread calls _cts.Cancel(), the worker thread observes cancellation from inside Task.Delay, throws OperationCanceledException, and the task completes — Wait() returns.

On Unity WebGL (single-threaded emscripten) Task.Run schedules on the same main loop as Unity. Task.Delay's continuation is also scheduled on that main loop. When Quit() triggers Dispose(), _workerTask.Wait() synchronously blocks the main thread waiting for a continuation that can only run on the main thread. Classic deadlock.

Confirmed by single-line ablation: setting options.EnableBackpressureHandling = false on WebGL avoids constructing the monitor at all and eliminates the wedge. Bisected version-wise: 3.2.4 (pre-BackpressureMonitor) ✅, 4.0.0 ❌, 4.3.1 ❌, 4.3.1 + workaround ✅.

[linear-code]

NET-684

[jamescrosswell]

Thanks for reporting this @ruslan-kodable - there's quite a lot going on in the steps to reproduce this. Do you think it would be possible to reproduce this more simply (e.g. in a console app - which would also be single threaded)?

If you could provide a small/simple reproducible example of the problem, that would definitely make it easier for one of us to look into it.

Edit: without having reproduced it, so just speculating, we could probably avoid by either:

1. Disabling back pressure management in single threaded environments like WebAssembly
2. Use IAsyncDisposable... which would only work if we could cascade async all the way up

[github-actions]

👋 Thanks for the report! We've added the Needs Reproduction label because we need a minimal reproduction to investigate further.

Please provide a link to a public GitHub repository that reproduces the issue with as little code as possible. Our repro guide has tips on how to create one.

Some quick hints:

• Start from a fresh dotnet new console (or similar) project
• Add only the Sentry NuGet package(s) relevant to the bug
• Include the exact SDK version number and your SentrySdk.Init / UseSentry call (with the DSN blanked out)

Alternatively, if the issue only manifests in your own codebase, you could try gradually removing code until you have a minimal repro.

[dingsdax]

I've created a reproduction for this issue: getsentry/repro#48

It simulates Unity WebGL's single-threaded environment using a custom SynchronizationContext and confirms the deadlock in BackpressureMonitor.Dispose() — _workerTask.Wait() blocks the only thread that could process the cancellation continuation.

Run it with:

docker build -t backpressure-deadlock .
docker run --rm backpressure-deadlock

🤖 Generated with Claude Code