{"record":{"id":"85402a473997bca3","repo":"swc-project/swc","slug":"swc-core-was-not-able-to-resolve-native-bindings","errorCode":null,"errorMessage":"@swc/core was not able to resolve native bindings installation. It'll try to use @swc/wasm as fallback instead.","messagePattern":"@swc/core was not able to resolve native bindings installation\\. It'll try to use @swc/wasm as fallback instead\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/core/src/postinstall.ts","lineNumber":65,"sourceCode":"    try {\n        binding = require(\"./binding.js\");\n\n        // Check if binding binary actually works.\n        // For the latest version, checks target triple. If it's old version doesn't have target triple, use parseSync instead.\n        const triple = binding.getTargetTriple\n            ? binding.getTargetTriple()\n            : binding.parseSync(\n                  \"console.log()\",\n                  Buffer.from(JSON.stringify({ syntax: \"ecmascript\" }))\n              );\n        assert.ok(triple, \"Failed to read target triple from native binary.\");\n    } catch (error: any) {\n        // if error is unsupported architecture, ignore to display.\n        if (!error.message?.includes(\"Unsupported architecture\")) {\n            console.warn(error);\n        }\n\n        console.warn(\n            `@swc/core was not able to resolve native bindings installation. It'll try to use @swc/wasm as fallback instead.`\n        );\n    }\n\n    if (!!binding) {\n        return;\n    }\n\n    // User choose to override the binary installation. Skip remanining validation.\n    if (!!process.env[\"SWC_BINARY_PATH\"]) {\n        console.warn(\n            `@swc/core could not resolve native bindings installation, but found manual override config SWC_BINARY_PATH specified. Skipping remaning validation.`\n        );\n        return;\n    }\n\n    // Check if top-level package.json installs @swc/wasm separately already\n    let wasmBinding;","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/swc-project/swc/blob/5176682b65416c6b5de6b47379ae1588ea3ecb3f/packages/core/src/postinstall.ts#L47-L83","documentation":"Postinstall warning from @swc/core: requiring ./binding.js (the platform-specific optional dependency) or validating it (getTargetTriple/parseSync) threw, so the native binary is unusable and @swc/core will fall back to @swc/wasm at runtime - meaning slower transforms. The script then tries to auto-install a matching @swc/wasm unless SWC_BINARY_PATH is set or @swc/wasm already resolves.","triggerScenarios":"npm install where @swc/core-linux-x64-gnu (or the darwin/win32 variant) is missing or broken: --no-optional installs, stale lockfiles, unsupported architecture (the 'Unsupported architecture' message is suppressed), musl/glibc mismatch, corrupted download, or Node too old for the prebuilt napi binary.","commonSituations":"CI with npm_config_optional=false, yarn/pnpm hoisting quirks, Alpine images, exotic archs (e.g. linux-arm64 musl), corporate proxies corrupting tarballs, Node version upgrades breaking native addons.","solutions":["Reinstall with optional dependencies: npm install --include=optional (and delete package-lock.json/node_modules if the lockfile omits the platform package).","Verify the expected platform package resolves: ls node_modules/@swc | grep core- and require.resolve it from your app.","On musl/exotic platforms, install @swc/wasm explicitly (npm i -D @swc/wasm) to make the fallback deterministic.","If you build the binary yourself, set SWC_BINARY_PATH to it so postinstall validation is skipped intentionally.","Report genuinely broken prebuilt binaries at swc-project/swc with your platform and Node version."],"exampleFix":"# before: warning during postinstall, wasm fallback at runtime\nnpm install --no-optional\n\n# after: proper native binding\nrm -rf node_modules package-lock.json\nnpm install --include=optional\nnode -e \"const b=require('@swc/core'); console.log(typeof b.transformFileSync)\"","handlingStrategy":"validation","validationCode":"// Postinstall-time preflight: confirm the platform binding resolves and loads.\nconst os = require('os');\nconst fs = require('fs');\nconst path = require('path');\nfunction preflightNativeBinding(): void {\n  const { optionalDependencies = {} } = require('@swc/core/package.json');\n  const tri = `${os.platform()}-${os.arch()}`;\n  const expected = Object.keys(optionalDependencies).filter((d) => d.startsWith(`@swc/core-${tri}`));\n  const present = expected.filter((d) => {\n    try { require.resolve(d); return true; } catch { return false; }\n  });\n  if (expected.length > 0 && present.length === 0) {\n    console.error(`Missing native binding (${expected.join(', ')}). Fix: npm install --include=optional`);\n    process.exitCode = 1;\n  } else {\n    require('@swc/core').transformSync('var a = 1'); // smoke test\n  }\n}","typeGuard":"function nativeBindingInstalled(): boolean {\n  const os = require('os');\n  const { optionalDependencies = {} } = require('@swc/core/package.json');\n  const tri = `@swc/core-${os.platform()}-${os.arch()}`;\n  return Object.keys(optionalDependencies).some(\n    (d) => d.startsWith(tri) && (() => { try { require.resolve(d); return true; } catch { return false; } })()\n  );\n}","tryCatchPattern":null,"preventionTips":["Never install with --no-optional; keep the platform package in package-lock.json.","Run a require('@swc/core').transformSync smoke test in CI after install to catch fallback mode early.","On musl or unusual platforms, add @swc/wasm as an explicit dependency for deterministic fallback.","Upgrade Node and @swc/core together; stale prebuilt napi binaries are a common load failure."],"tags":["postinstall","native-binding","optional-dependencies","fallback","node"],"backgroundTag":"native-binding-missing","analyzedSha":"5176682b65416c6b5de6b47379ae1588ea3ecb3f","analyzedAt":"2026-08-17T16:16:52.067Z","contentChangedAt":"2026-08-17T16:16:52.067Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}