swc-project/swc · critical · Error

Bindings not found.

Error message

Bindings not found.

What it means

At import time @swc/core tries to load its native Node-API binding (the local binding.js / platform-specific optional package, or the file named by SWC_BINARY_PATH) and falls back to @swc/wasm when that fails. Compiler.minify() reaches this throw only when neither is available — both `bindings` and `fallbackBindings` ended up falsy. It signals a broken installation or a toolchain that shelled the native require to an empty module, never a bad minify() argument.

Source

Thrown at packages/core/src/index.ts:155

    return (mod) => {
        let m = mod;
        for (const p of ps) {
            m = p(m);
        }
        return m;
    };
}

export class Compiler {
    private fallbackBindingsPluginWarningDisplayed = false;

    async minify(src: string | Buffer, opts?: JsMinifyOptions, extras?: NapiMinifyExtra): Promise<Output> {
        if (bindings) {
            return bindings.minify(Buffer.from(!Buffer.isBuffer(src) && typeof src === 'object' ? JSON.stringify(src) : src), toBuffer(opts ?? {}), !Buffer.isBuffer(src) && typeof src === 'object', extras ?? {});
        } else if (fallbackBindings) {
            return fallbackBindings.minify(src, opts);
        }
        throw new Error("Bindings not found.");
    }

    minifySync(src: string | Buffer, opts?: JsMinifyOptions, extras?: NapiMinifyExtra): Output {
        if (bindings) {
            return bindings.minifySync(Buffer.from(!Buffer.isBuffer(src) && typeof src === 'object' ? JSON.stringify(src) : src), toBuffer(opts ?? {}), !Buffer.isBuffer(src) && typeof src === 'object', extras ?? {});
        } else if (fallbackBindings) {
            return fallbackBindings.minifySync(src, opts);
        }
        throw new Error("Bindings not found.");
    }

    /**
     * @deprecated Use Rust instead.
     */
    parse(
        src: string,
        options: ParseOptions & { isModule: false }
    ): Promise<Script>;

View on GitHub (pinned to 5176682b65)

Solutions

1. Clean-reinstall with optional dependencies enabled: `rm -rf node_modules package-lock.json && npm install` and remove any --no-optional / omit=optional setting
2. Verify the platform binding package matches your OS/arch: `npm ls @swc/core-linux-x64-gnu` (or -musl, darwin-arm64, win32-x64-msvc); add it explicitly as an optionalDependency if installs keep skipping it
3. If SWC_BINARY_PATH is set, make sure it points to a loadable .node file; otherwise unset it so the normal resolver runs
4. Add @swc/wasm as an explicit dependency so minify() can run on the fallback
5. Bundler users: mark @swc/core as external or alias it to @swc/wasm so the binding require is not stubbed

Example fix

# before: compiler.minify() throws 'Bindings not found.'
npm ls '@swc/core-*' # platform package missing

# after: reinstall with optional platform packages enabled
rm -rf node_modules package-lock.json && npm install --include=optional

const { Compiler } = require('@swc/core');
// Fail fast at boot instead of mid-build.
function assertSwcBindingsAvailable() {
  try {
    new Compiler().minifySync('let x=1');
  } catch (e) {
    if (e instanceof Error && /Bindings not found/.test(e.message)) {
      throw new Error('SWC install broken: reinstall @swc/core with optional platform packages or add @swc/wasm.');
    }
    throw e;
  }
}

try {
  out = await compiler.minify(src, opts);
} catch (e) {
  if (e instanceof Error && /Bindings not found/.test(e.message)) {
    throw new Error('SWC native bindings missing — clean reinstall required (do not skip optional deps).');
  }
  throw e;
}

When it happens

Trigger: `await new Compiler().minify(code, opts)` in an environment where require('./binding.js') failed and require('@swc/wasm') also failed or resolved to nothing: optional dependencies skipped, node_modules pruned or copied between platforms, SWC_BINARY_PATH pointing at a missing/corrupt .node file, or a bundler shimming the native require.

Common situations: npm/pnpm installs with --no-optional / --omit=optional or .npmrc omit=optional; Docker multi-stage builds copying node_modules from a different base image; alpine (musl) images missing the musl platform package; yarn PnP without unplugging @swc/core; bundlers (webpack/esbuild) shimming the .node require to an empty module.

Related errors

• Bindings not found
• Invalid attempt to iterate non-iterable instance. In order t
• Fallback bindings does not support this interface yet.
• Fallback bindings does not support filesystem access.
• Fallback bindings does not support filesystem access

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