swc-project/swc · warning

@swc/core was not able to resolve native bindings installati

Error message

@swc/core was not able to resolve native bindings installation. It'll try to use @swc/wasm as fallback instead.

What it means

Postinstall warning from @swc/core: requiring ./binding.js (the platform-specific optional dependency) or validating it (getTargetTriple/parseSync) threw, so the native binary is unusable and @swc/core will fall back to @swc/wasm at runtime - meaning slower transforms. The script then tries to auto-install a matching @swc/wasm unless SWC_BINARY_PATH is set or @swc/wasm already resolves.

Source

Thrown at packages/core/src/postinstall.ts:65

    try {
        binding = require("./binding.js");

        // Check if binding binary actually works.
        // For the latest version, checks target triple. If it's old version doesn't have target triple, use parseSync instead.
        const triple = binding.getTargetTriple
            ? binding.getTargetTriple()
            : binding.parseSync(
                  "console.log()",
                  Buffer.from(JSON.stringify({ syntax: "ecmascript" }))
              );
        assert.ok(triple, "Failed to read target triple from native binary.");
    } catch (error: any) {
        // if error is unsupported architecture, ignore to display.
        if (!error.message?.includes("Unsupported architecture")) {
            console.warn(error);
        }

        console.warn(
            `@swc/core was not able to resolve native bindings installation. It'll try to use @swc/wasm as fallback instead.`
        );
    }

    if (!!binding) {
        return;
    }

    // User choose to override the binary installation. Skip remanining validation.
    if (!!process.env["SWC_BINARY_PATH"]) {
        console.warn(
            `@swc/core could not resolve native bindings installation, but found manual override config SWC_BINARY_PATH specified. Skipping remaning validation.`
        );
        return;
    }

    // Check if top-level package.json installs @swc/wasm separately already
    let wasmBinding;

View on GitHub (pinned to 5176682b65)

Solutions

1. Reinstall with optional dependencies: npm install --include=optional (and delete package-lock.json/node_modules if the lockfile omits the platform package).
2. Verify the expected platform package resolves: ls node_modules/@swc | grep core- and require.resolve it from your app.
3. On musl/exotic platforms, install @swc/wasm explicitly (npm i -D @swc/wasm) to make the fallback deterministic.
4. If you build the binary yourself, set SWC_BINARY_PATH to it so postinstall validation is skipped intentionally.
5. Report genuinely broken prebuilt binaries at swc-project/swc with your platform and Node version.

Example fix

# before: warning during postinstall, wasm fallback at runtime
npm install --no-optional

# after: proper native binding
rm -rf node_modules package-lock.json
npm install --include=optional
node -e "const b=require('@swc/core'); console.log(typeof b.transformFileSync)"

// Postinstall-time preflight: confirm the platform binding resolves and loads.
const os = require('os');
const fs = require('fs');
const path = require('path');
function preflightNativeBinding(): void {
  const { optionalDependencies = {} } = require('@swc/core/package.json');
  const tri = `${os.platform()}-${os.arch()}`;
  const expected = Object.keys(optionalDependencies).filter((d) => d.startsWith(`@swc/core-${tri}`));
  const present = expected.filter((d) => {
    try { require.resolve(d); return true; } catch { return false; }
  });
  if (expected.length > 0 && present.length === 0) {
    console.error(`Missing native binding (${expected.join(', ')}). Fix: npm install --include=optional`);
    process.exitCode = 1;
  } else {
    require('@swc/core').transformSync('var a = 1'); // smoke test
  }
}

function nativeBindingInstalled(): boolean {
  const os = require('os');
  const { optionalDependencies = {} } = require('@swc/core/package.json');
  const tri = `@swc/core-${os.platform()}-${os.arch()}`;
  return Object.keys(optionalDependencies).some(
    (d) => d.startsWith(tri) && (() => { try { require.resolve(d); return true; } catch { return false; } })()
  );
}

When it happens

Trigger: npm install where @swc/core-linux-x64-gnu (or the darwin/win32 variant) is missing or broken: --no-optional installs, stale lockfiles, unsupported architecture (the 'Unsupported architecture' message is suppressed), musl/glibc mismatch, corrupted download, or Node too old for the prebuilt napi binary.

Common situations: CI with npm_config_optional=false, yarn/pnpm hoisting quirks, Alpine images, exotic archs (e.g. linux-arm64 musl), corporate proxies corrupting tarballs, Node version upgrades breaking native addons.

Related errors

• @swc/core could not resolve native bindings installation, bu
• Fallback bindings does not support legacy plugins, it'll be
• failed to handle: {s}
• failed to handle with unknown panic message
• failed to execute transfomred code

AI-assisted analysis of swc-project/swc@5176682b65 (2026-08-17). Data as JSON: /api/errors/85402a473997bca3. Report an issue: GitHub.