FuelLabs/fuels-ts · error · Error

Unsupported platform ${process.platform}.${process.platform

Error message

Unsupported platform ${process.platform}.${process.platform === 'win32' ? ' If you are on Windows, please use WSL.' : ''}

What it means

Thrown by `getPkgPlatform()` in the forc installer when `process.platform` is neither `darwin` nor `linux`. The forc binaries are only published for macOS and Linux; Windows users must run under WSL. Fires during the forc postinstall before any download is attempted.

Source

Thrown at internal/forc/lib/shared.js:39

};

const binaries = [
  'forc',
  'forc-crypto',
  'forc-debug',
  'forc-deploy',
  'forc-doc',
  'forc-fmt',
  'forc-lsp',
  'forc-migrate',
  'forc-run',
  'forc-submit',
  'forc-tx',
];

export const getPkgPlatform = () => {
  if (process.platform !== 'darwin' && process.platform !== 'linux') {
    throw new Error(
      `Unsupported platform ${process.platform}.${
        process.platform === 'win32' ? ' If you are on Windows, please use WSL.' : ''
      }}`
    );
  }
  if (process.arch !== 'arm64' && process.arch !== 'x64') {
    throw new Error(`Unsupported arch ${process.arch}`);
  }
  return platforms[process.platform][process.arch];
};

export const versionFilePath = join(__dirname, '../VERSION');

export const getCurrentVersion = () => {
  const versionContents = readFileSync(versionFilePath, 'utf8');
  const forcVersion = versionContents.match(/^.+$/m)?.[0] || versionContents;
  return forcVersion;
};

View on GitHub (pinned to b3f37c91ac)

Solutions

On Windows: install WSL2 (`wsl --install`), then run the install inside a WSL shell where `process.platform` reports `linux`.
On other unsupported OSes: run the build inside a Linux container (e.g. `ubuntu` image).
If you maintain a fork with extra binaries, extend the `platforms` map in `internal/forc/lib/shared.js` to include the new platform before calling `getPkgPlatform`.

Example fix

// before (PowerShell on native Windows)
$ pnpm install
// throws: Unsupported platform win32. If you are on Windows, please use WSL.

// after (WSL)
$ wsl -d Ubuntu
$ pnpm install

Defensive patterns

Strategy: validation

Validate before calling

// gate before invoking the installer
const SUPPORTED_PLATFORMS = new Set(['darwin', 'linux']);
if (!SUPPORTED_PLATFORMS.has(process.platform)) {
  throw new Error(
    `Refusing to install forc on ${process.platform}. Use WSL on Windows or a Linux/macOS host.`
  );
}

Prevention

On Windows, always run project setup inside WSL2; document this in your README.
Use a Linux/macOS Docker image for CI to guarantee `process.platform` is supported.
Detect the platform in a preinstall script and print an actionable message before the unsupported installer runs.

When it happens

Trigger: Running `npm/pnpm/yarn install` on native Windows (platform `win32`), FreeBSD (`freebsd`), Solaris (`sunos`), or AIX (`aix`). The Windows branch appends a hint to use WSL.

Common situations: Developers on Windows who have not enabled/entered WSL; CI runners pinned to a Windows image without WSL; cross-platform Docker images built `FROM` a non-linux base.

Related errors

AI-assisted analysis of FuelLabs/fuels-ts@b3f37c91ac (2026-08-12). Data as JSON: /api/errors/d5d4baf9017f23cf. Report an issue: GitHub.