[NativeAOT] Set `_UseNativeLibPrefix=true` to fix UnsatisfiedLinkError on Android by Copilot · Pull Request #10825 · dotnet/android

Copilot · 2026-02-17T20:32:51Z

NativeAOT Android apps crash on startup with UnsatisfiedLinkError at System.loadLibrary because the native binary may not have the required lib prefix in the APK.

dotnet/runtime#118299 changed ComputeLinkedFilesToPublish to derive the native binary path from $(NativeBinary) (which includes $(NativeBinaryPrefix)) instead of %(IntermediateAssembly.Filename), and introduced opt-in _UseNativeLibPrefix to control the lib prefix. Android's System.loadLibrary("X") requires libX.so — we should opt in.

Changes in `Microsoft.Android.Sdk.NativeAOT.targets`:

Set _UseNativeLibPrefix=true so the NativeAOT SDK produces libTargetName.so natively, matching Android's library naming requirement
Use $(NativeBinaryPrefix) in soname instead of hardcoded lib prefix, keeping soname consistent with the actual binary filename
Handle both naming cases in _AndroidFixNativeLibraryFileName — add lib prefix when missing (backward compat), and explicitly set ArchiveFileName when the runtime already added it via $(NativeBinaryPrefix)

<!-- Tell NativeAOT SDK to produce the binary with "lib" prefix -->
<_UseNativeLibPrefix Condition=" '$(_UseNativeLibPrefix)' == '' ">true</_UseNativeLibPrefix>

<!-- Soname now uses $(NativeBinaryPrefix) instead of hardcoded "lib" -->
<LinkerArg Include="&quot;-Wl,-soname,$(NativeBinaryPrefix)$(TargetName)$(NativeBinaryExt)&quot;" />

Original prompt

This section details on the original issue you should resolve

<issue_title>NativeAOT Android app crashes with UnsatisfiedLinkError using 10.0.103</issue_title>
<issue_description>### Android framework version

net10.0-android

Affected platform version

Workload 10.0.103

Description

Our Android app using NativeAOT crashes on startup when built with workload 10.0.103. The same app builds and runs correctly with workload 10.0.102. No code changes between the two builds.

Stacktrace:

Exception java.lang.UnsatisfiedLinkError:
  at java.lang.Runtime.loadLibrary0 (Runtime.java:1097)
  at java.lang.Runtime.loadLibrary0 (Runtime.java:1019)
  at java.lang.System.loadLibrary (System.java:1765)
  at net.dot.jni.nativeaot.JavaInteropRuntime.<clinit> (JavaInteropRuntime.java:8)
  at net.dot.jni.nativeaot.NativeAotRuntimeProvider.attachInfo (NativeAotRuntimeProvider.java:38)
  at android.app.ActivityThread.installProvider (ActivityThread.java:9021)
  at android.app.ActivityThread.installContentProviders (ActivityThread.java:8536)
  at android.app.ActivityThread.handleBindApplication (ActivityThread.java:8191)
  at android.app.ActivityThread.-$$Nest$mhandleBindApplication (Unknown Source)
  at android.app.ActivityThread$H.handleMessage (ActivityThread.java:2642)
  at android.os.Handler.dispatchMessage (Handler.java:107)
  at android.os.Looper.loopOnce (Looper.java:282)
  at android.os.Looper.loop (Looper.java:387)
  at android.app.ActivityThread.main (ActivityThread.java:9500)
  at java.lang.reflect.Method.invoke
  at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run (RuntimeInit.java:600)
  at com.android.internal.os.ZygoteInit.main (ZygoteInit.java:1005)

I have only tested our app with this.
I haven't been able to try 11.0.100-preview.1 owing to an issue with the UseDotNet@2 task and preview sdks.

Steps to Reproduce

I have only tested our app with this.

Project configuration:

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>
		<TargetFramework>net10.0-android</TargetFramework>
		<OutputType>Exe</OutputType>
		<RootNamespace>...</RootNamespace>
		<AssemblyName>...</AssemblyName>
		<SupportedOSPlatformVersion>26.0</SupportedOSPlatformVersion>
		<RuntimeIdentifiers>android-x64;android-arm64</RuntimeIdentifiers>
		<AndroidPackageFormats>aab</AndroidPackageFormats>
		<UseMauiEssentials>true</UseMauiEssentials>
		<InvariantGlobalization>true</InvariantGlobalization>
	</PropertyGroup>
	<PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
		<PublishAot>true</PublishAot>
		<AndroidLinkTool>r8</AndroidLinkTool>
	</PropertyGroup>

Did you find any workaround?

Pin maui-android workload to 10.0.102

Relevant log output

```</issue_description>

<agent_instructions>Try to use `git bisect` and find out if something went wrong in dotnet/android repo.

If you can't find it, search what might have release in dotnet/runtime/release/10.0 branch that could also be the cause.</agent_instructions>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@jonathanpeppers</author><body>
I don't see a commit related to NativeAOT in this range:
* https://github.com/dotnet/android/compare/36.1.12...36.1.30

We did improve some things in main, @grendello is there a fix related to NativeAOT we should backport?</body></comment_new>
</comments>

Fixes NativeAOT Android app crashes with UnsatisfiedLinkError using 10.0.103 #10822

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Set _UseNativeLibPrefix=true so the NativeAOT SDK produces the native binary with the "lib" prefix from the start (e.g. libMyApp.so). Android requires native libraries to have this prefix. Also update soname to use $(NativeBinaryPrefix) for consistency and make _AndroidFixNativeLibraryFileName handle both cases (with and without NativeBinaryPrefix) for backward compatibility. Fixes #10822 Co-authored-by: jonathanpeppers <840039+jonathanpeppers@users.noreply.github.com>

MichalStrehovsky

When this underscored property was added, we very specifically did not want dotnet/android to set it: dotnet/runtime#118299 (comment)

jonathanpeppers · 2026-02-19T22:08:31Z

I questioned if copilot's fix here was correct. Should we actually remove this line instead?

android/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.NativeAOT.targets

Lines 135 to 136 in 265a63b

    
           <!-- Android needs a proper soname property or it will refuse to load the library --> 
        
           <LinkerArg Include="&quot;-Wl,-soname,lib$(TargetName)$(NativeBinaryExt)&quot;" />

I've been trying to get a maestro update that shows something broken, but it seems like the recent .NET SDK (vmr) builds are OK.

MichalStrehovsky · 2026-02-19T22:15:28Z

I questioned if copilot's fix here was correct. Should we actually remove this line instead?

android/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.NativeAOT.targets

Lines 245 to 250 in 265a63b

    
           <Target Name="_AndroidFixNativeLibraryFileName" AfterTargets="ComputeFilesToPublish"> 
        
             <ItemGroup> 
        
               <!-- Fix paths to contain lib-prefix --> 
        
               <ResolvedFileToPublish Update="@(ResolvedFileToPublish)" ArchiveFileName="lib%(FileName)%(Extension)" Condition=" '%(Filename)%(Extension)' == '$(TargetName)$(NativeBinaryExt)' " /> 
        
             </ItemGroup> 
        
           </Target>

is also setting the lib prefix. If this broke in 10.0 servicing, I wonder if some SDK change made these hacks stop working.

It would have been much better to introduce a mechanism in dotnet/runtime than hacking around it like this.

kayodebristol · 2026-03-02T17:27:04Z

@copilot This PR is showing successful CI! 🎉

Status: ✅ All checks passing
Ready for: Review and potential draft → ready conversion

The NativeAOT UnsatisfiedLinkError fix appears to be working. Consider:

Running a final test to ensure the fix works as expected
Converting from draft to ready for review if testing passes
Requesting review from the NativeAOT team

Action needed: Final validation and mark ready for review.

Initial plan

7f81a6c

Copilot AI assigned Copilot and jonathanpeppers Feb 17, 2026

Copilot started work on behalf of jonathanpeppers February 17, 2026 20:33 View session

Copilot AI changed the title ~~[WIP] Fix NativeAOT Android app crash with UnsatisfiedLinkError~~ [NativeAOT] Set _UseNativeLibPrefix=true to fix UnsatisfiedLinkError on Android Feb 17, 2026

Copilot AI requested a review from jonathanpeppers February 17, 2026 21:28

Copilot finished work on behalf of jonathanpeppers February 17, 2026 21:28

jonathanpeppers mentioned this pull request Feb 18, 2026

NativeAOT Android app crashes with UnsatisfiedLinkError using 10.0.103 #10822

Open

MichalStrehovsky suggested changes Feb 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[NativeAOT] Set `_UseNativeLibPrefix=true` to fix UnsatisfiedLinkError on Android#10825

[NativeAOT] Set `_UseNativeLibPrefix=true` to fix UnsatisfiedLinkError on Android#10825
Copilot wants to merge 2 commits intomainfrom
copilot/fix-android-app-crash

Copilot AI commented Feb 17, 2026 •

edited

Loading

Uh oh!

MichalStrehovsky left a comment

Uh oh!

jonathanpeppers commented Feb 19, 2026

Uh oh!

MichalStrehovsky commented Feb 19, 2026

Uh oh!

kayodebristol commented Mar 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Copilot AI commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes in Microsoft.Android.Sdk.NativeAOT.targets:

Affected platform version

Description

Steps to Reproduce

Did you find any workaround?

Relevant log output

Uh oh!

MichalStrehovsky left a comment

Choose a reason for hiding this comment

Uh oh!

jonathanpeppers commented Feb 19, 2026

Uh oh!

MichalStrehovsky commented Feb 19, 2026

Uh oh!

kayodebristol commented Mar 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Feb 17, 2026 •

edited

Loading

Changes in `Microsoft.Android.Sdk.NativeAOT.targets`: