oraios/serena · error · RuntimeError

foundry forge does not publish a Windows {arch} npm package

Error message

foundry forge does not publish a Windows {arch} npm package

What it means

On Windows, Foundry publishes forge only as an amd64 npm package. _get_forge_npm_package raises this RuntimeError when os.name == 'nt' but the detected architecture is arm64, since no Windows ARM forge npm package exists.

Source

Thrown at src/solidlsp/language_servers/solidity_language_server.py:164

            return solidity_executable_path

        @staticmethod
        def _get_forge_npm_package() -> str:
            """
            Returns the platform-specific @foundry-rs forge npm subpackage name. Installing
            the meta-package fails on Windows due to a POSIX-only postinstall script.
            """
            machine = platform.machine().lower()
            if machine in ("x86_64", "amd64"):
                arch = "amd64"
            elif machine in ("arm64", "aarch64"):
                arch = "arm64"
            else:
                raise RuntimeError(f"Unsupported architecture for foundry forge: {machine}")

            if os.name == "nt":
                if arch != "amd64":
                    raise RuntimeError(f"foundry forge does not publish a Windows {arch} npm package")
                return "@foundry-rs/forge-win32-amd64"
            if platform.system() == "Darwin":
                return f"@foundry-rs/forge-darwin-{arch}"
            return f"@foundry-rs/forge-linux-{arch}"

        def create_launch_command_env(self) -> dict[str, str]:
            solidity_language_server_version = self._custom_settings.get(
                "solidity_language_server_version", DEFAULT_SOLIDITY_LANGUAGE_SERVER_VERSION
            )
            forge_version = self._custom_settings.get("forge_version", DEFAULT_FORGE_VERSION)
            solidity_ls_dir = self._resolve_solidity_ls_dir(solidity_language_server_version, forge_version)
            managed_bin_dir = os.path.join(solidity_ls_dir, "node_modules", ".bin")
            return {"PATH": managed_bin_dir + os.pathsep + os.environ.get("PATH", "")}

        def _resolve_solidity_ls_dir(self, solidity_language_server_version: str, forge_version: str) -> str:
            # legacy unversioned dir reserved for INITIAL pair; any other combination goes into a versioned subdir
            is_initial = (
                solidity_language_server_version == INITIAL_SOLIDITY_LANGUAGE_SERVER_VERSION and forge_version == INITIAL_FORGE_VERSION

View on GitHub (pinned to 7fcbca7e62)

Solutions

Run the workload under x86_64 emulation (Windows 11 ARM's built-in x64 emulation) using an amd64 Python/Node.
Install forge natively via foundryup instead of the npm route and point the server at it.
Use an x64 virtual machine, WSL2 x86_64 image, or a cloud/dev container on amd64.
Track Foundry releases for a future Windows arm64 npm package.

Example fix

// before: arm64 Windows native Python/Node
// after: x64 toolchain under Windows ARM emulation
winget install Python.Python.3.12 --architecture x64

Defensive patterns

Strategy: validation

Validate before calling

import platform, os
if os.name == "nt" and platform.machine().lower() not in ("amd64", "x86_64"):
    raise SystemExit("Windows ARM: run under x64 emulation or install forge via foundryup")

Type guard

def windows_forge_supported() -> bool:
    import platform, os
    if os.name != "nt":
        return True
    return platform.machine().lower() in ("amd64", "x86_64")

Try / catch

try:
    server = SolidityLanguageServer(config, repo_root, settings)
except RuntimeError as e:
    if "Windows" in str(e) and "npm package" in str(e):
        raise SystemExit("Install forge via foundryup and configure its path, or use an x64 environment") from e
    raise

Prevention

On Windows ARM devices, use x64 Python/Node under Windows' built-in emulation.
Prefer WSL2 (x86_64) for Solidity toolchains on ARM hardware.
Document architecture requirements in your project's setup docs.

When it happens

Trigger: Starting the Solidity language server on Windows-on-ARM (e.g. Surface Pro X, ARM Windows laptops) where platform.machine() reports arm64/aarch64.

Common situations: Windows ARM devices or Windows ARM VMs; developers assuming Windows support implies all architectures.

Related errors

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/7dfbc3f157c51896. Report an issue: GitHub.