{"record":{"id":"2445824e22ba4fd2","repo":"swc-project/swc","slug":"fallback-bindings-does-not-support-this-interface","errorCode":null,"errorMessage":"Fallback bindings does not support this interface yet.","messagePattern":"Fallback bindings does not support this interface yet\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/index.ts","lineNumber":188,"sourceCode":"    parse(\n        src: string,\n        options: ParseOptions & { isModule: false }\n    ): Promise<Script>;\n    parse(\n        src: string,\n        options?: ParseOptions,\n        filename?: string\n    ): Promise<Module>;\n    async parse(\n        src: string,\n        options?: ParseOptions,\n        filename?: string\n    ): Promise<Program> {\n        options = options || { syntax: \"ecmascript\" };\n        options.syntax = options.syntax || \"ecmascript\";\n\n        if (!bindings && !!fallbackBindings) {\n            throw new Error(\n                \"Fallback bindings does not support this interface yet.\"\n            );\n        } else if (!bindings) {\n            throw new Error(\"Bindings not found.\");\n        }\n\n        if (bindings) {\n            const res = await bindings.parse(src, toBuffer(options), filename);\n            return parseProgramJson(res);\n        } else if (fallbackBindings) {\n            return fallbackBindings.parse(src, options);\n        }\n        throw new Error(\"Bindings not found.\");\n    }\n\n    parseSync(src: string, options: ParseOptions & { isModule: false }): Script;\n    parseSync(src: string, options?: ParseOptions, filename?: string): Module;\n    parseSync(src: string, options?: ParseOptions, filename?: string): Program {","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/swc-project/swc/blob/5176682b65416c6b5de6b47379ae1588ea3ecb3f/packages/core/src/index.ts#L170-L206","documentation":"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.","triggerScenarios":"`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().","commonSituations":"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.","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"],"exampleFix":"# before: WASM fallback active, compiler.parse() throws\nnode -e \"new (require('@swc/core').Compiler)().parseSync('1')\"\n# -> Fallback bindings does not support this interface yet.\n\n# after: native platform package restored\nnpm install --include=optional\nnode -e \"new (require('@swc/core').Compiler)().parseSync('1')\"","handlingStrategy":"validation","validationCode":"const { Compiler } = require('@swc/core');\nfunction detectSwcMode() {\n  try {\n    new Compiler().parseSync(''); // native-only API as probe\n    return 'native';\n  } catch (e) {\n    if (e instanceof Error && /does not support this interface|Bindings not found/.test(e.message)) {\n      return 'wasm-fallback';\n    }\n    throw e;\n  }\n}\n// Route parse() callers only when detectSwcMode() === 'native'","typeGuard":null,"tryCatchPattern":"try {\n  const program = await compiler.parse(src, opts);\n} catch (e) {\n  if (e instanceof Error && /Fallback bindings does not support this interface/.test(e.message)) {\n    // running on @swc/wasm — use transform()/transformSync() instead, or fix the native install\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["swc","wasm-fallback","parse","native-bindings"],"backgroundTag":"wasm-fallback-limitations","analyzedSha":"5176682b65416c6b5de6b47379ae1588ea3ecb3f","analyzedAt":"2026-08-17T16:16:52.067Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}