[Migration] DOTNET_DiagnosticPorts in Environment.txt causes silent app freeze when upgrading from .NET 10 (Mono) to .NET 11 (CoreCLR)

[janne-hmp]

Android framework version

net11.0-android (Preview)

Affected platform version

Android 16

Description

As per the post by @davidortinau last week, we have been testing how .NET 11 Preview 6 compares with .NET 10. We noticed that when upgrading a .NET MAUI Android application from .NET 10 (Mono) to .NET 11 (CoreCLR), the application silently freezes at startup and then exits with code 0 if the project's Platforms/Android/Environment.txt contains:

DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend,connect

This setting was commonly used (and sometimes recommended) for Mono debugging on Android. On the Mono runtime, the Xamarin debugger tooling handled this diagnostic port connection seamlessly. However, on CoreCLR in .NET 11, the runtime interprets this literally; it suspends at startup and waits indefinitely for a diagnostic client to send a ResumeStartup command via IPC. Since the VS debugger doesn't connect using this mechanism on CoreCLR, the app hangs and eventually exits silently.

Why This Is Critical

• Silent failure: The app exits with code 0 and no crash, exception, or error message. There is no indication of what went wrong.
• Difficult to diagnose: The only clue is a single line in logcat: The runtime has been configured to pause during startup and is awaiting a Diagnostics IPC ResumeStartup command from a Diagnostic Port. which is easily missed or misinterpreted.
• Common configuration: Many existing .NET Android projects have this line in Environment.txt from Mono/Xamarin-era setup guides.
• Migration trap: Developers upgrading to .NET 11 will hit this immediately with no obvious path to resolution.

Expected Behavior

One or more of the following:

1. A build warning when targeting .NET 11 CoreCLR and Environment.txt contains DOTNET_DiagnosticPorts with suspend alerting the developer that this is incompatible with CoreCLR on Android.
2. A migration guide entry documenting that this setting must be removed when upgrading from Mono to CoreCLR.
3. The runtime or Android tooling ignoring or overriding the suspend mode when launched from the IDE debugger.

Actual Behavior

The app silently hangs at startup and exits with code 0. No error, no crash, no warning.

Environment

• .NET SDK: 11.0.100-preview.6 (or later)
• Previous SDK: .NET 10 (Mono runtime)
• Platform: Android (arm64)
• IDE: Visual Studio 2026

Steps to Reproduce

1. Take any .NET MAUI Android project that was previously targeting net10.0-android.
2. Ensure Platforms/Android/Environment.txt contains:

   DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend,connect
   

3. Change TargetFrameworks to net11.0-android.
4. Build and deploy to an Android device.
5. The app will launch, appear to do nothing, and then exit silently.

Did you find any workaround?

Remove the DOTNET_DiagnosticPorts line from Environment.txt:

-DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend,connect
 MONO_GC_PARAMS=nursery-size=128m

Relevant log output

### Logcat Output


I/DOTNET  (27334): The runtime has been configured to pause during startup and is awaiting a Diagnostics IPC ResumeStartup command from a Diagnostic Port.
I/DOTNET  (27334): DOTNET_DiagnosticPorts="127.0.0.1:9000,suspend,connect"
I/DOTNET  (27334): DOTNET_DefaultDiagnosticPortSuspend=0
The program 'MyApp.dll' has exited with code 0 (0x0).

[jonathanpeppers]

suspend tells the runtime to block until it can attach to a profiler. This is so you can measure startup time.

Do you want the nosuspend setting instead?

This is the help text when I run:

$ dotnet-dsrouter android
How to connect current dotnet-dsrouter pid=1234 with android device and diagnostics tooling.
Build and run your application on android device such as:
[Default Tracing]
dotnet build -t:Run -c Release -p:DiagnosticAddress=127.0.0.1 -p:DiagnosticPort=9000 -p:DiagnosticSuspend=false -p:DiagnosticListenMode=connect
[Startup Tracing]
dotnet build -t:Run -c Release -p:DiagnosticAddress=127.0.0.1 -p:DiagnosticPort=9000 -p:DiagnosticSuspend=true -p:DiagnosticListenMode=connect

You might take a look at:

• https://github.com/dotnet/android/blob/main/Documentation/guides/tracing.md

It shows some simpler options instead of setting $DOTNET_DiagnosticPorts directly.

[janne-hmp]

@jonathanpeppers This was merely to highlight that someone switching from .NET 10 to .NET 11 may be likely to have these debugging options set, but due to the silent nature of the crash, it may be difficult to figure out why the app suddenly crashes at start with .NET 11. It is just an unwelcome migration problem, and depending on whether one manages to figure this out or not, it can be pretty critical, as the app does not start at all anymore.

[jonathanpeppers]

This didn't change from .NET 10 to 11? suspend blocks until attached in .NET 10 as well.

For what you are seeing, can you enable extra logging and share full adb logcat output?

# more logging
adb shell setprop debug.mono.log default,assembly,timing=bare,mono_log_level=debug,mono_log_mask=all
# clear the log
adb logcat -c
# cause the crash
# save the log
adb logcat -d > log.txt

[janne-hmp]

No, not for Mono Runtime. But what did change is the runtime itself, i.e., in .NET 11 the default is now CoreCLR on Android. If you start CoreCLR / .NET 11 with the old DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend,connect intended for Mono Runtime in .NET 10, which you probably do if you just simply upgrade from .NET 10, CoreCLR hangs waiting indefinitely for a debugger to attach and the app gets killed by Android. All of this happens rather silently and the problem is in a very special file that may be difficult to locate. In any case, this is not a good migration experience to .NET 11 from .NET 10, so the situation probably should be handled by some extra check somewhere, at least to point the user to the right direction.

[jonathanpeppers]

Mono uses the same setting, I have seen it block/wait on suspend as well.

I'm still not seeing a difference between .NET 10 and 11, did you try using the MSBuild properties mentioned in:

• https://github.com/dotnet/android/blob/main/Documentation/guides/tracing.md

Maybe you would have a better experience with simplified workflow: run dotnet-trace --dsrouter + MSBuild properties only.

[janne-hmp]

@jonathanpeppers If you use DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend,connect with CoreCLR, do the .NET 11 apps start normally for you? In our experience, they do not start at all. We do have a good development experience with both CoreCLR and Mono runtimes, but with the right settings only.

[jonathanpeppers]

There is another error I have seen, but it isn't silent at all, the app crashes with a stack trace:

• [net11.0-android/CoreCLR] DOTNET_EnableEventPipe via AndroidEnvironment aborts app at startup (SIGABRT) instead of writing a trace #12161 (comment)

[janne-hmp]

@jonathanpeppers Thanks for the link to the other related problem that has been observed earlier. Whether it results in a loud crash with a stack trace (like the DOTNET_EnableEventPipe issue in #12161 ) or a silent freeze (like this DOTNET_DiagnosticPorts=...suspend issue), they both stem from the same root cause: stale Environment.txt configurations that developers are carrying over from .NET 10 / Mono that suddenly break the app on .NET 11 / CoreCLR.

And appreciated the note on the tracing guide as well. I understand suspend is working exactly as designed on CoreCLR; it acts as a hard synchronization gate that blocks before managed code runs, which is correct for startup profiling.

But because of the migration experience, developers will likely hit these traps when retargeting to net11.0-android without realizing their old Environment.txt is the culprit.

Since the build system already processes Environment.txt, would it be feasible to add a build-time warning when AndroidEnvironment files contain these known problematic variables? For example, if it detects DOTNET_DiagnosticPorts with suspend (or DOTNET_EnableEventPipe), it could emit a warning like:

XA0XXX: Environment.txt sets DOTNET_DiagnosticPorts with 'suspend', which will block app startup on CoreCLR until a diagnostic tool connects. Consider using MSBuild properties (-p:DiagnosticSuspend=true) or 'nosuspend' instead. See https://github.com/dotnet/android/blob/main/Documentation/guides/tracing.md

Catching these at build time would save developers a lot of debugging time compared to relying on migration docs or deciphering logcat crashes/hangs. For our project, we've already removed the line and everything works fine; the idea here is just to smooth the migration path for others.

[jonathanpeppers]

No, we aren't going to add a warning for DOTNET_DiagnosticPorts, as it would warn when you profile any app! LOL?

If you are getting a similar stack trace to what I linked above can you share it? We need a fix in the dotnet/runtime repo for that.