What causes "Bindings not found" in swc-project/swc?

Clean-reinstall with optionals enabled: `rm -rf node_modules package-lock.json && npm install --include=optional`

swc-project/swc · critical · Error

Bindings not found

Error message

Bindings not found

What it means

Final throw of Compiler.transformSync() (this message variant has no trailing period): the native branch and the fallback branch both failed to match, so neither the Node-API binding nor @swc/wasm is available in the process. The @swc/core installation is broken — transformSync() was never even attempted against an engine.

Source

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

            return bindings.transformSync(
                isModule ? stringifyProgram(src) : src,
                isModule,
                toBuffer(newOptions)
            );
        } else if (fallbackBindings) {
            if (plugin && !this.fallbackBindingsPluginWarningDisplayed) {
                console.warn(
                    `Fallback bindings does not support legacy plugins, it'll be ignored.`
                );
                this.fallbackBindingsPluginWarningDisplayed = true;
            }
            return fallbackBindings.transformSync(
                isModule ? JSON.stringify(src) : src,
                options
            );
        }

        throw new Error("Bindings not found");
    }

    async transformFile(path: string, options?: Options): Promise<Output> {
        if (!bindings && !!fallbackBindings) {
            throw new Error(
                "Fallback bindings does not support filesystem access."
            );
        } else if (!bindings) {
            throw new Error("Bindings not found.");
        }

        options = options || {};

        if (options?.jsc?.parser) {
            options.jsc.parser.syntax =
                options.jsc.parser.syntax ?? "ecmascript";
        }

View on GitHub (pinned to 5176682b65)

Solutions

Clean-reinstall with optionals enabled: `rm -rf node_modules package-lock.json && npm install --include=optional`
Verify the platform binding package for the runtime (`npm ls @swc/core-linux-x64-gnu` or your variant)
Validate or unset SWC_BINARY_PATH
Install @swc/wasm explicitly — transformSync() works on the fallback

Example fix

# before: compiler.transformSync(src) -> 'Bindings not found'

# after
rm -rf node_modules package-lock.json && npm install --include=optional
node -e "new (require('@swc/core').Compiler)().transformSync('let x=1')"

Defensive patterns

Strategy: validation

Validate before calling

const { Compiler } = require('@swc/core');
function assertSwcBindingsAvailable() {
  try {
    new Compiler().transformSync('');
  } catch (e) {
    if (e instanceof Error && /Bindings not found/.test(e.message)) {
      throw new Error('SWC install broken: reinstall with optional platform packages or add @swc/wasm.');
    }
    throw e;
  }
}

Try / catch

try {
  const out = compiler.transformSync(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;
}

Prevention

Probe transformSync with empty input at process start in loaders/jest transformers
Assert the platform-specific binding package resolves in CI after every install
Install @swc/wasm explicitly so synchronous transforms keep working even if native loading fails

When it happens

Trigger: `compiler.transformSync(src, opts)` where require('./binding.js') failed and require('@swc/wasm') failed or resolved to nothing: skipped optional dependencies, pruned or cross-platform node_modules, invalid SWC_BINARY_PATH, bundler-shimmed native require.

Common situations: Synchronous SWC paths in build tools (loaders, jest transformers) in CI installed with --omit=optional; Docker images built on a different libc/arch; corrupted node_modules.

Related errors

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