dotnet/maui · error · Exception

Error: Building dotnet-samples with NativeAOT is only suppor

Error message

Error: Building dotnet-samples with NativeAOT is only supported in Release configuration

What it means

Thrown by the 'dotnet-samples' Cake target when NativeAOT compilation is requested (USE_NATIVE_AOT=true) but the build configuration is Debug. NativeAOT ahead-of-time compilation for the iOS HostApp sample is only validated/supported in Release mode, so the script aborts before invoking MSBuild rather than producing a broken AOT binary.

Source

Thrown at eng/cake/dotnet.cake:184

        if (useNuget)
        {
            properties = new Dictionary<string, string>
            {
                ["UseWorkload"] = "true",
                // ["GenerateAppxPackageOnBuild"] = "true",
                ["RestoreConfigFile"] = tempDir.CombineWithFilePath("NuGet.config").FullPath,
            };
        }

        string projectsToBuild;
        if (USE_NATIVE_AOT)
        {
            if (configuration.Equals("Debug", StringComparison.OrdinalIgnoreCase))
            {
                var errMsg = $"Error: Building dotnet-samples with NativeAOT is only supported in Release configuration";
                Error(errMsg);
                throw new Exception(errMsg);
            }
            projectsToBuild = "./src/Controls/tests/TestCases.HostApp/Controls.TestCases.HostApp.csproj";
            properties["_UseNativeAot"] = "true";
            properties["RuntimeIdentifier"] = "iossimulator-x64";
            properties["BuildIpa"] = "true";
        }
        else
        {
            projectsToBuild = "./eng/Microsoft.Maui.Samples.slnf";
        }

        RunMSBuildWithDotNet(projectsToBuild, properties, binlogPrefix: "sample-");
    });

// Builds the host app for the UI Tests
Task("uitests-apphost")
    .IsDependentOn("dotnet-buildtasks")
    .Does(() =>

View on GitHub (pinned to f377ff1c5e)

Solutions

Pass --configuration=Release (or set the configuration argument/variable to Release) when running the dotnet-samples target with NativeAOT enabled.
If you did not intend NativeAOT, unset/disable USE_NATIVE_AOT so the standard Microsoft.Maui.Samples.slnf solution filter builds instead.
In CI, ensure the NativeAOT job matrix step sets configuration=Release explicitly before invoking cake.

Example fix

// before
cake --target=dotnet-samples --use_native_aot=true
// after
cake --target=dotnet-samples --use_native_aot=true --configuration=Release

Defensive patterns

Strategy: validation

Validate before calling

// Validate before invoking the samples target
if (USE_NATIVE_AOT && configuration.Equals("Debug", StringComparison.OrdinalIgnoreCase)) {
    Information("NativeAOT requires Release; forcing configuration=Release.");
    configuration = "Release";
}

Prevention

Make the NativeAOT CI job explicitly set configuration=Release in the matrix.
Document that USE_NATIVE_AOT implies Release near the property assignments.
Consider auto-correcting Debug->Release with a warning instead of throwing for local runs.

When it happens

Trigger: Invoking the samples build with both USE_NATIVE_AOT enabled and configuration set to "Debug" (case-insensitive). The check is configuration.Equals("Debug", StringComparison.OrdinalIgnoreCase) inside the `if (USE_NATIVE_AOT)` block at dotnet.cake:184.

Common situations: Running the samples target locally with a default Debug configuration, or a CI job that sets USE_NATIVE_AOT=true without overriding configuration to Release. Also happens when a developer copies a NativeAOT job template but forgets the -configuration=Release argument.

Related errors

AI-assisted analysis of dotnet/maui@f377ff1c5e (2026-08-13). Data as JSON: /api/errors/dfb57adc1a2c8f94. Report an issue: GitHub.