{"record":{"id":"039320c168aa7bcb","repo":"run-llama/liteparse","slug":"failed-to-load-native-module-for-platform-arc","errorCode":null,"errorMessage":"Failed to load native module for ${platform}-${arch}. Ensure the correct optional dependency is installed.","messagePattern":"Failed to load native module for (.+?)-(.+?)\\. Ensure the correct optional dependency is installed\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/node/src/native.ts","lineNumber":433,"sourceCode":"  // Try several paths since __dirname may be dist/ or dist/src/\n  const searchDirs = [__dirname, join(__dirname, \"..\"), join(__dirname, \"..\", \"..\")];\n  // Try full triple names (e.g. liteparse.linux-x64-gnu.node) and simple name\n  const fileNames = [\n    ...candidates.map((c) => `liteparse.${c}.node`),\n    `liteparse.${platform}-${arch}.node`,\n    \"liteparse.node\",\n  ];\n  for (const dir of searchDirs) {\n    for (const fileName of fileNames) {\n      try {\n        return require(join(dir, fileName));\n      } catch {\n        // try next\n      }\n    }\n  }\n\n  throw new Error(\n    `Failed to load native module for ${platform}-${arch}. ` +\n      `Ensure the correct optional dependency is installed.`,\n  );\n}\n\nexport const native = loadNative();\n","sourceCodeStart":415,"sourceCodeEnd":440,"githubUrl":"https://github.com/run-llama/liteparse/blob/22d2dd8cd7f7b9320102b57ddaf0e663ff7d15a8/packages/node/src/native.ts#L415-L440","documentation":"loadNative() tries each candidate @liteparse platform-specific optional dependency for the current platform/architecture and throws this when none can be required. It means the native binary for this OS/CPU pair is missing — usually because optional dependencies were skipped during install or the platform package does not exist for this environment. The module-level `export const native = loadNative()` makes this fire at import time of native.ts.","triggerScenarios":"`npm install` with `--no-optional` or `--omit=optional`; installing with a package manager that mishandles os/cpu-conditional optional deps (older yarn 1, some pnpm configs); running on an unsupported or exotic platform (Alpine musl without the matching build, FreeBSD); corrupted node_modules where the platform package folder is missing.","commonSituations":"Docker images using `npm ci --omit=optional` for slim builds; switching Node version/package manager without reinstalling; corporate registries that filter platform-specific packages; deploying to a platform not covered by published prebuilds.","solutions":["Reinstall dependencies with optional deps enabled: `npm install` (avoid `--omit=optional`).","Verify the matching package exists in node_modules, e.g. `ls node_modules/@liteparse/liteparse-linux-x64-gnu`, and reinstall if absent.","Confirm the runtime platform/arch is supported (`node -p \"process.platform + '-' + process.arch\"`) and matches a published prebuild.","In Docker, don't delete platform packages in the final stage; use `npm ci` with default settings.","If on an unsupported platform, build the native crate from source or use a supported base image (e.g. debian instead of alpine)."],"exampleFix":"// before (Dockerfile)\nRUN npm ci --omit=optional\n// after\nRUN npm ci","handlingStrategy":"fallback","validationCode":"import { createRequire } from 'module';\nconst req = createRequire(import.meta.url);\nconst pkg = `@liteparse/liteparse-${process.platform}-${process.arch}`;\nlet ok = false;\ntry { req.resolve(pkg); ok = true; } catch {}\nif (!ok) console.error(`Native package ${pkg} is not installed — reinstall without --omit=optional`);","typeGuard":"const hasNative = () => {\n  try { require.resolve(`@liteparse/liteparse-${process.platform}-${process.arch}`); return true; }\n  catch { return false; }\n};","tryCatchPattern":"let lp;\ntry {\n  lp = new LiteParse();\n} catch (e) {\n  if (e.message.startsWith('Failed to load native module')) {\n    console.error('Native binary missing. Run: npm install (with optional deps enabled).');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Never install with --omit=optional / --no-optional for this package.","Pin and verify supported os/cpu in CI; run a smoke import test in the deploy pipeline.","When using pnpm/yarn, confirm platform-specific optional deps are actually materialized in node_modules.","Check platform/arch support before deploying to a new base image (e.g. alpine)."],"tags":["node","native-module","installation","platform"],"backgroundTag":"missing-optional-dependency","analyzedSha":"22d2dd8cd7f7b9320102b57ddaf0e663ff7d15a8","analyzedAt":"2026-09-08T06:09:49.009Z","contentChangedAt":"2026-09-08T06:09:49.009Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}