{"record":{"id":"a80cfaf8263b4f92","repo":"swc-project/swc","slug":"bindings-not-found","errorCode":null,"errorMessage":"Bindings not found.","messagePattern":"Bindings not found\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/core/src/index.ts","lineNumber":155,"sourceCode":"    return (mod) => {\n        let m = mod;\n        for (const p of ps) {\n            m = p(m);\n        }\n        return m;\n    };\n}\n\nexport class Compiler {\n    private fallbackBindingsPluginWarningDisplayed = false;\n\n    async minify(src: string | Buffer, opts?: JsMinifyOptions, extras?: NapiMinifyExtra): Promise<Output> {\n        if (bindings) {\n            return bindings.minify(Buffer.from(!Buffer.isBuffer(src) && typeof src === 'object' ? JSON.stringify(src) : src), toBuffer(opts ?? {}), !Buffer.isBuffer(src) && typeof src === 'object', extras ?? {});\n        } else if (fallbackBindings) {\n            return fallbackBindings.minify(src, opts);\n        }\n        throw new Error(\"Bindings not found.\");\n    }\n\n    minifySync(src: string | Buffer, opts?: JsMinifyOptions, extras?: NapiMinifyExtra): Output {\n        if (bindings) {\n            return bindings.minifySync(Buffer.from(!Buffer.isBuffer(src) && typeof src === 'object' ? JSON.stringify(src) : src), toBuffer(opts ?? {}), !Buffer.isBuffer(src) && typeof src === 'object', extras ?? {});\n        } else if (fallbackBindings) {\n            return fallbackBindings.minifySync(src, opts);\n        }\n        throw new Error(\"Bindings not found.\");\n    }\n\n    /**\n     * @deprecated Use Rust instead.\n     */\n    parse(\n        src: string,\n        options: ParseOptions & { isModule: false }\n    ): Promise<Script>;","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/swc-project/swc/blob/5176682b65416c6b5de6b47379ae1588ea3ecb3f/packages/core/src/index.ts#L137-L173","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Clean-reinstall with optional dependencies enabled: `rm -rf node_modules package-lock.json && npm install` and remove any --no-optional / omit=optional setting","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","If SWC_BINARY_PATH is set, make sure it points to a loadable .node file; otherwise unset it so the normal resolver runs","Add @swc/wasm as an explicit dependency so minify() can run on the fallback","Bundler users: mark @swc/core as external or alias it to @swc/wasm so the binding require is not stubbed"],"exampleFix":"# before: compiler.minify() throws 'Bindings not found.'\nnpm ls '@swc/core-*' # platform package missing\n\n# after: reinstall with optional platform packages enabled\nrm -rf node_modules package-lock.json && npm install --include=optional","handlingStrategy":"validation","validationCode":"const { Compiler } = require('@swc/core');\n// Fail fast at boot instead of mid-build.\nfunction assertSwcBindingsAvailable() {\n  try {\n    new Compiler().minifySync('let x=1');\n  } catch (e) {\n    if (e instanceof Error && /Bindings not found/.test(e.message)) {\n      throw new Error('SWC install broken: reinstall @swc/core with optional platform packages or add @swc/wasm.');\n    }\n    throw e;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  out = await compiler.minify(src, opts);\n} catch (e) {\n  if (e instanceof Error && /Bindings not found/.test(e.message)) {\n    throw new Error('SWC native bindings missing — clean reinstall required (do not skip optional deps).');\n  }\n  throw e;\n}","preventionTips":["Run a boot-time smoke test (minifySync on trivial input) so install breakage fails the pipeline immediately","Never install with --no-optional / --omit=optional while @swc/core is in the tree; assert the platform package exists in CI","Install dependencies in the same image/arch that runs them; don't copy node_modules across musl/glibc or arch boundaries","Keep @swc/wasm pinned as an explicit fallback dependency","If overriding SWC_BINARY_PATH, validate the path in the deploy script"],"tags":["swc","native-bindings","install","minify","node-api"],"backgroundTag":"native-bindings-not-found","analyzedSha":"5176682b65416c6b5de6b47379ae1588ea3ecb3f","analyzedAt":"2026-08-17T16:16:52.067Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}