Xamarin.iOS "MT-/mtouch ... failed" in CI

By Kaveh Alemi·Latchkey

mtouch is the Xamarin.iOS tool that AOT-compiles and links the native iOS app. An mtouch (MT-prefixed) error means that step failed, commonly due to a missing Xcode, an unresolved native symbol, or a linking problem.

What this error means

A Xamarin.iOS build fails during mtouch with an MT-prefixed error (for example MT2002 unresolved symbol, MT0091 SDK mismatch, or a generic "mtouch exited with code 1").

error MT2002: Failed to resolve "System.Void Foo::Bar()" reference from "MyApp".
error MT0000: Unexpected error - the 'mtouch' task failed (exit code 1).

Common causes

Missing or wrong Xcode on the macOS runner

mtouch drives the Apple toolchain; without a selected, compatible Xcode it cannot link the native app.

A linker-stripped or unresolved native symbol

Aggressive linking or a missing reference leaves a symbol unresolved, so mtouch fails to produce the binary.

How to fix it

Build on macOS with a compatible Xcode

1. Run the iOS build on a macOS runner.
2. Select an Xcode that matches the Xamarin.iOS version.
3. Rebuild so mtouch has the Apple toolchain.

runs-on: macos-13
steps:
  - run: sudo xcode-select -s /Applications/Xcode_14.3.app
  - run: msbuild MyApp.iOS/MyApp.iOS.csproj /p:Configuration=Release /p:Platform=iPhone

Adjust linker behavior for unresolved symbols

If the linker strips a needed symbol, relax linking for that build or preserve the type so mtouch resolves it.

msbuild MyApp.iOS/MyApp.iOS.csproj /p:MtouchLink=SdkOnly

How to prevent it

• Build Xamarin.iOS on macOS with a matching Xcode.
• Preserve types the linker would otherwise strip.
• Read the MT error code to target the specific cause.

Frequently asked questions

Related guides

References

• .NET documentation
• GitHub Actions documentation