{"record":{"id":"302aca2acc3d50b8","repo":"swc-project/swc","slug":"swc-core-could-not-resolve-native-bindings-instal","errorCode":null,"errorMessage":"@swc/core could not resolve native bindings installation, but found manual override config SWC_BINARY_PATH specified. Skipping remaning validation.","messagePattern":"@swc/core could not resolve native bindings installation, but found manual override config SWC_BINARY_PATH specified\\. Skipping remaning validation\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"info","filePath":"packages/core/src/postinstall.ts","lineNumber":76,"sourceCode":"        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;\n    try {\n        wasmBinding = require.resolve(`@swc/wasm`);\n    } catch (_) {}\n\n    if (!!wasmBinding && existsSync(wasmBinding)) {\n        return;\n    }\n\n    const env = { ...process.env, npm_config_global: undefined };\n    const { version } = require(path.join(\n        path.dirname(require.resolve(\"@swc/core\")),","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/swc-project/swc/blob/5176682b65416c6b5de6b47379ae1588ea3ecb3f/packages/core/src/postinstall.ts#L58-L94","documentation":"Postinstall message from @swc/core: the platform-specific native binding could not be resolved (missing optional dependency, unsupported arch, or load failure), but the SWC_BINARY_PATH environment variable is set, meaning the user manually points to a native binary. The script then skips the remaining validation - including auto-installing the @swc/wasm fallback - and trusts the override.","triggerScenarios":"npm install where the platform optional dependency is absent (--no-optional, lockfile quirks, unsupported arch) while SWC_BINARY_PATH is exported (e.g. CI images, napi overrides, local debugging builds).","commonSituations":"CI images prebuilding SWC from source and pointing SWC_BINARY_PATH at it; Alpine/musl or exotic architectures without prebuilt bindings; users forgetting the env var is still set globally, silently bypassing fallback installation.","solutions":["Verify SWC_BINARY_PATH points to an existing, working binary for the current platform (node -e \"require('@swc/core').transformSync('1')\").","If the override is stale, unset it and reinstall so normal binding resolution and the @swc/wasm fallback work again.","Reinstall with optional dependencies included: npm install --include=optional (or fix the lockfile) so the native package resolves normally.","Preinstall @swc/wasm yourself if you intentionally run without native bindings."],"exampleFix":"# before: stale override silently skips fallback setup\nexport SWC_BINARY_PATH=/old/path/libswc.node\nnpm install\n\n# after: verify or drop the override\nnode -e \"console.log(require('fs').existsSync(process.env.SWC_BINARY_PATH))\" || unset SWC_BINARY_PATH\nnpm install --include=optional","handlingStrategy":"validation","validationCode":"// Preflight: confirm the override actually works instead of trusting it.\nconst fs = require('fs');\nfunction validateBinaryOverride(): void {\n  const p = process.env.SWC_BINARY_PATH;\n  if (!p) return;\n  if (!fs.existsSync(p)) {\n    throw new Error(`SWC_BINARY_PATH points to a missing file: ${p}`);\n  }\n  require('@swc/core').transformSync('var a = 1'); // smoke-test the binding\n}","typeGuard":"function hasBinaryOverride(): boolean {\n  return typeof process.env.SWC_BINARY_PATH === 'string' && process.env.SWC_BINARY_PATH.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Set SWC_BINARY_PATH only in the environments that build the custom binary; unset it elsewhere.","Smoke-test require('@swc/core').transformSync after install when the override is active.","Document the override in the repo so CI images stay in sync with it."],"tags":["postinstall","native-binding","env-var","swc-binary-path","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-14T05:17:10.506Z"}