swc-project/swc · info

@swc/core could not resolve native bindings installation, bu

Error message

@swc/core could not resolve native bindings installation, but found manual override config SWC_BINARY_PATH specified. Skipping remaning validation.

What it means

Postinstall message from @swc/core: the platform-specific native binding could not be resolved (missing optional dependency, unsupported arch, or load failure), but the SWC_BINARY_PATH environment variable is set, meaning the user manually points to a native binary. The script then skips the remaining validation - including auto-installing the @swc/wasm fallback - and trusts the override.

Source

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

        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;
    try {
        wasmBinding = require.resolve(`@swc/wasm`);
    } catch (_) {}

    if (!!wasmBinding && existsSync(wasmBinding)) {
        return;
    }

    const env = { ...process.env, npm_config_global: undefined };
    const { version } = require(path.join(
        path.dirname(require.resolve("@swc/core")),

View on GitHub (pinned to 5176682b65)

Solutions

1. Verify SWC_BINARY_PATH points to an existing, working binary for the current platform (node -e "require('@swc/core').transformSync('1')").
2. If the override is stale, unset it and reinstall so normal binding resolution and the @swc/wasm fallback work again.
3. Reinstall with optional dependencies included: npm install --include=optional (or fix the lockfile) so the native package resolves normally.
4. Preinstall @swc/wasm yourself if you intentionally run without native bindings.

Example fix

# before: stale override silently skips fallback setup
export SWC_BINARY_PATH=/old/path/libswc.node
npm install

# after: verify or drop the override
node -e "console.log(require('fs').existsSync(process.env.SWC_BINARY_PATH))" || unset SWC_BINARY_PATH
npm install --include=optional

// Preflight: confirm the override actually works instead of trusting it.
const fs = require('fs');
function validateBinaryOverride(): void {
  const p = process.env.SWC_BINARY_PATH;
  if (!p) return;
  if (!fs.existsSync(p)) {
    throw new Error(`SWC_BINARY_PATH points to a missing file: ${p}`);
  }
  require('@swc/core').transformSync('var a = 1'); // smoke-test the binding
}

function hasBinaryOverride(): boolean {
  return typeof process.env.SWC_BINARY_PATH === 'string' && process.env.SWC_BINARY_PATH.length > 0;
}

When it happens

Trigger: npm install where the platform optional dependency is absent (--no-optional, lockfile quirks, unsupported arch) while SWC_BINARY_PATH is exported (e.g. CI images, napi overrides, local debugging builds).

Common situations: CI images prebuilding SWC from source and pointing SWC_BINARY_PATH at it; Alpine/musl or exotic architectures without prebuilt bindings; users forgetting the env var is still set globally, silently bypassing fallback installation.

Related errors

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

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