Xamarin.Android "The \"Aapt2Compile\"/\"Aapt2Link\" task failed" in CI

By Kaveh Alemi·Latchkey

Xamarin.Android runs AAPT2 through MSBuild tasks like Aapt2Compile and Aapt2Link. When one fails unexpectedly, either the aapt2 binary is missing from the installed build-tools or a resource cannot be compiled.

What this error means

A Xamarin.Android build fails with "The \"Aapt2Compile\" task failed unexpectedly" or "The \"Aapt2Link\" task failed", sometimes with an inner message that aapt2 could not be found.

error MSB4018: The "Aapt2Compile" task failed unexpectedly.
System.ComponentModel.Win32Exception: aapt2: cannot execute binary file
(build-tools not installed).

Common causes

Android build-tools (with aapt2) not installed

AAPT2 ships in the Android build-tools. If the runner lacks the build-tools package, the task cannot find or run aapt2.

An invalid resource breaks the task

A malformed or mis-named resource makes the compile/link task throw rather than emit a clean APT2 diagnostic.

How to fix it

Install Android build-tools

1. Install a build-tools package with sdkmanager.
2. Confirm ANDROID_HOME points at the SDK that has it.
3. Rebuild so the Aapt2 tasks find aapt2.

sdkmanager "build-tools;34.0.0"
export ANDROID_HOME=$ANDROID_SDK_ROOT

Fix the offending resource

Read the inner exception, then correct the invalid or mis-named resource file before rebuilding.

dotnet clean
msbuild MyApp.Android/MyApp.Android.csproj /p:Configuration=Release

How to prevent it

• Install Android build-tools so aapt2 is available.
• Keep ANDROID_HOME pointed at the SDK with build-tools.
• Validate Android resources before committing.

Frequently asked questions

Related guides

References

• .NET documentation
• GitHub Actions documentation