diff --git a/Documentation/guides/messages/xa1038.md b/Documentation/guides/messages/xa1038.md
new file mode 100644
index 00000000000..50fd6486f59
--- /dev/null
+++ b/Documentation/guides/messages/xa1038.md
@@ -0,0 +1,49 @@
+---
+title: Xamarin.Android error XA1038
+description: XA1038 error code
+ms.date: 12/6/2023
+---
+# Xamarin.Android error XA1038
+
+## Example messages
+
+```
+error XA1038: $(TargetPlatformVersion) 33 is not a valid target for `net8.0-android` projects. Please update your $(TargetPlatformVersion) to a supported version (e.g. 34).
+```
+
+## Issue
+
+This error indicates that you have a mismatch between the
+`$(TargetPlatformVersion)` set and what .NET Android supports.
+
+For example:
+
+```xml
+
+ net8.0-android33
+
+```
+
+In this case, .NET 8 targets Android 34, which is the default and valid
+`$(TargetPlatformVersion)`, but the `$(TargetPlatformVersion)` is set to 33.
+`TargetFramework=net8.0-android33` above is shorthand for:
+
+```xml
+
+ net8.0
+ android
+ 33.0
+
+```
+
+## Solution
+
+Change the value of the `$(TargetPlatformVersion)` property to match a supported
+version for the `$(TargetFramework)`, or remove the value entirely to rely on
+the default:
+
+```xml
+
+ net8.0-android
+
+```
diff --git a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/in/Microsoft.Android.Sdk.BundledVersions.in.targets b/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/in/Microsoft.Android.Sdk.BundledVersions.in.targets
index 607626dc3b1..e5b1d9ee266 100644
--- a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/in/Microsoft.Android.Sdk.BundledVersions.in.targets
+++ b/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/in/Microsoft.Android.Sdk.BundledVersions.in.targets
@@ -10,12 +10,16 @@ WARNING: DO NOT MODIFY this file unless you are knowledgeable about MSBuild and
@ANDROID_PACK_VERSION_LONG@
@ANDROID_PACK_VERSION_LONG@
+ <_AndroidLatestStableApiLevel>@ANDROID_LATEST_STABLE_API_LEVEL@
<_AndroidTargetingPackId Condition="$(TargetPlatformVersion.EndsWith('.0'))">$(TargetPlatformVersion.Substring(0, $(TargetPlatformVersion.LastIndexOf('.0'))))
<_AndroidTargetingPackId Condition="'$(_AndroidTargetingPackId)' == ''">$(TargetPlatformVersion)
- <_AndroidRuntimePackId Condition=" '$(_AndroidTargetingPackId)' < '@ANDROID_LATEST_STABLE_API_LEVEL@' ">@ANDROID_LATEST_STABLE_API_LEVEL@
+
+ <_AndroidErrorOnTargetPlatformVersion Condition=" '$(_AndroidTargetingPackId)' != '$(_AndroidLatestStableApiLevel)' ">$(_AndroidTargetingPackId)
+ <_AndroidTargetingPackId Condition=" '$(_AndroidTargetingPackId)' != '$(_AndroidLatestStableApiLevel)' ">$(_AndroidLatestStableApiLevel)
<_AndroidRuntimePackId Condition=" '$(_AndroidRuntimePackId)' == '' ">$(_AndroidTargetingPackId)
+ <_AndroidRuntimePackId Condition=" '$(_AndroidRuntimePackId)' != '$(_AndroidLatestStableApiLevel)' ">$(_AndroidLatestStableApiLevel)
+
+ $(TargetPlatformVersion) {0} is not a valid target for '{1}' projects. Please update your $(TargetPlatformVersion) to a supported version (e.g. {2}).
+ The following are literal names and should not be translated: $(TargetPlatformVersion).
+{0} - the invalid $(TargetPlatformVersion) such as 33
+{1} - the $(TargetFramework) such as net8.0-android
+{2} - the valid $(TargetPlatformVersion) such as 34
+
\ No newline at end of file
diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BuildTest.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BuildTest.cs
index f0819191393..1ea210b1376 100644
--- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BuildTest.cs
+++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BuildTest.cs
@@ -806,6 +806,28 @@ public void IfAndroidJarDoesNotExistThrowXA5207 ([Values(true, false)] bool buil
Directory.Delete (AndroidSdkDirectory, recursive: true);
}
+ [Test]
+ public void InvalidTargetPlatformVersion ([Values ("android33", "android35.0")] string platformVersion)
+ {
+ const string targetFramework = "net9.0";
+ var project = new XamarinAndroidApplicationProject {
+ TargetFramework = $"{targetFramework}-{platformVersion}",
+ };
+ using var builder = CreateApkBuilder ();
+ builder.ThrowOnBuildFailure = false;
+ Assert.IsFalse (builder.Build (project), "build should fail");
+
+ Assert.IsTrue (int.TryParse (platformVersion.Replace ("android", "").Replace (".0", ""), out var apiLevel), "failed to parse API level!");
+
+ int maxApiLevel = AndroidSdkResolver.GetMaxInstalledPlatform ();
+ if (apiLevel > maxApiLevel) {
+ Assert.IsTrue (builder.LastBuildOutput.ContainsText ("error NETSDK1140:"), "NETSDK1140 should have been raised.");
+ } else {
+ var message = $"error XA1038: $(TargetPlatformVersion) {apiLevel} is not a valid target for '{targetFramework}' projects.";
+ Assert.IsTrue (builder.LastBuildOutput.ContainsText (message), "XA1038 should have been raised.");
+ }
+ }
+
[Test]
public void XA4212 ()
{
diff --git a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets
index ad337416ebb..2b20ff5ebc1 100644
--- a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets
+++ b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets
@@ -545,6 +545,11 @@ Copyright (C) 2011-2012 Xamarin. All rights reserved.
ResourceName="XA1035"
Condition=" '$(BundleAssemblies)' == 'true' and '$(UsingAndroidNETSdk)' == 'true' "
/>
+