dotnet/maui · error · Exception

PowerShell Core (pwsh) is required on non-Windows platforms.

Error message

PowerShell Core (pwsh) is required on non-Windows platforms. Please install it and try again.

What it means

Re-thrown on non-Windows platforms when any exception escapes the pwsh-availability check (the `catch (Exception ex) when (!IsRunningOnWindows())` filter). It wraps the original exception's message in an Error log and throws a clearer 'pwsh is required on non-Windows' message, since the cgmanifest update script is PowerShell-based and cannot run without pwsh.

Source

Thrown at eng/cake/dotnet.cake:606

        }
        else
        {
            var exitCode = StartProcess("which", new ProcessSettings
            {
                Arguments = "pwsh",
                RedirectStandardOutput = true,
                RedirectStandardError = true
            });
            if (exitCode != 0)
            {
                throw new Exception("PowerShell Core (pwsh) is not installed. Please install it to continue.");
            }
        }
    }
    catch (Exception ex) when (!IsRunningOnWindows())
    {
        Error("Error checking for pwsh: " + ex.Message);
        throw new Exception("PowerShell Core (pwsh) is required on non-Windows platforms. Please install it and try again.");
    }

    // Execute the PowerShell script
    StartProcess(pwshExecutable, new ProcessSettings
    {
        Arguments = "-NonInteractive -ExecutionPolicy Bypass -File ./eng/scripts/update-cgmanifest.ps1"
    });
});

Task("publicapi")
    .Description("Clears PublicAPI.Unshipped.txt files and regenerates them with current public APIs. Processes Core, Controls, Essentials, and Graphics projects. Skips Windows files on non-Windows platforms and always skips Tizen files. Use after adding new public APIs to resolve build errors.")
    .Does(() =>
{
    var corePublicApiDir = MakeAbsolute(Directory("./src/Core/src/PublicAPI"));
    var controlsPublicApiDir = MakeAbsolute(Directory("./src/Controls/src/Core/PublicAPI"));
    var essentialsPublicApiDir = MakeAbsolute(Directory("./src/Essentials/src/PublicAPI"));
    var graphicsPublicApiDir = MakeAbsolute(Directory("./src/Graphics/src/Graphics/PublicAPI"));

View on GitHub (pinned to f377ff1c5e)

Solutions

Install PowerShell Core on the non-Windows host (apt/brew) and confirm `pwsh --version` works.
Check the preceding 'Error checking for pwsh: <message>' log line for the original exception detail.
Ensure the user running cake has execute permission on the pwsh binary and that PATH includes its directory.

Defensive patterns

Strategy: validation

Validate before calling

// Validate platform + pwsh up front on non-Windows
if (!IsRunningOnWindows()) {
    var exitCode = StartProcess("which", new ProcessSettings { Arguments = "pwsh", RedirectStandardOutput = true });
    if (exitCode != 0)
        throw new Exception("Install PowerShell Core (pwsh) before running this task on Linux/macOS.");
}

Prevention

Bake pwsh into non-Windows CI images.
Surface the original exception message (ex.Message) in the re-throw so root cause is visible.
Narrow the catch filter to specific expected exceptions rather than catching all and re-wrapping.

When it happens

Trigger: Any exception inside the pwsh-detection try block (not just the `which` failure) while running on Linux/macOS. For example, StartProcess itself throwing, or the Windows-specific lookup path erroring when intercepted by the non-Windows filter.

Common situations: Same root causes as the pwsh-not-installed error but surfaced through the catch-all: a malformed PATH, a permission error invoking `which`, or a partial pwsh install. The non-Windows guard converts these into a single actionable message.

Related errors

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