swc-project/swc · error · Error

Fallback bindings does not support this interface yet.

Error message

Fallback bindings does not support this interface yet.

What it means

Compiler.parse() is implemented only by the native binding (it serializes the AST to JSON through the napi layer and post-processes it with parseProgramJson). When the native binary failed to load but the @swc/wasm fallback is present, the method refuses rather than silently degrading: it throws 'Fallback bindings does not support this interface yet.'. Seeing this error means your process is running on the WASM fallback while calling a native-only API.

Source

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

    parse(
        src: string,
        options: ParseOptions & { isModule: false }
    ): Promise<Script>;
    parse(
        src: string,
        options?: ParseOptions,
        filename?: string
    ): Promise<Module>;
    async parse(
        src: string,
        options?: ParseOptions,
        filename?: string
    ): Promise<Program> {
        options = options || { syntax: "ecmascript" };
        options.syntax = options.syntax || "ecmascript";

        if (!bindings && !!fallbackBindings) {
            throw new Error(
                "Fallback bindings does not support this interface yet."
            );
        } else if (!bindings) {
            throw new Error("Bindings not found.");
        }

        if (bindings) {
            const res = await bindings.parse(src, toBuffer(options), filename);
            return parseProgramJson(res);
        } else if (fallbackBindings) {
            return fallbackBindings.parse(src, options);
        }
        throw new Error("Bindings not found.");
    }

    parseSync(src: string, options: ParseOptions & { isModule: false }): Script;
    parseSync(src: string, options?: ParseOptions, filename?: string): Module;
    parseSync(src: string, options?: ParseOptions, filename?: string): Program {

View on GitHub (pinned to 5176682b65)

Solutions

Repair the native install so bindings load: clean reinstall with optional platform packages (`rm -rf node_modules package-lock.json && npm install --include=optional`)
Check SWC_BINARY_PATH — unset it or point it at a valid .node file
If you must stay on WASM, avoid this API: use transform()/transformSync() (supported by the fallback) to compile or produce the output you needed from parse()
Pin the matching platform package (e.g. @swc/core-linux-x64-gnu) as an explicit optionalDependency so it cannot be skipped

Example fix

# before: WASM fallback active, compiler.parse() throws
node -e "new (require('@swc/core').Compiler)().parseSync('1')"
# -> Fallback bindings does not support this interface yet.

# after: native platform package restored
npm install --include=optional
node -e "new (require('@swc/core').Compiler)().parseSync('1')"

Defensive patterns

Strategy: validation

Validate before calling

const { Compiler } = require('@swc/core');
function detectSwcMode() {
  try {
    new Compiler().parseSync(''); // native-only API as probe
    return 'native';
  } catch (e) {
    if (e instanceof Error && /does not support this interface|Bindings not found/.test(e.message)) {
      return 'wasm-fallback';
    }
    throw e;
  }
}
// Route parse() callers only when detectSwcMode() === 'native'

Try / catch

try {
  const program = await compiler.parse(src, opts);
} catch (e) {
  if (e instanceof Error && /Fallback bindings does not support this interface/.test(e.message)) {
    // running on @swc/wasm — use transform()/transformSync() instead, or fix the native install
  }
  throw e;
}

Prevention

Detect native vs fallback mode at boot and gate native-only APIs (parse/parseFile/print-of-AST) behind it
Repair installs so native bindings load: never skip optional platform packages
Document which @swc/core APIs are native-only when sharing config across environments

When it happens

Trigger: `await compiler.parse(src, { syntax: 'typescript' })` when require('./binding.js') failed (so @swc/wasm was loaded as fallback) — broken platform package, SWC_BINARY_PATH pointing at an unloadable binary, or an environment where native addons can't load; also when @swc/wasm is installed deliberately and code written against the full @swc/core API calls parse().

Common situations: Serverless/browser/WASM-first setups; postinstall scripts skipped so the platform-optional package never landed; teams prototyping with @swc/wasm then reusing the code with @swc/core's fallback path active.

Related errors

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