run-llama/liteparse · critical · Error

Failed to load native module for

Error message

Failed to load native module for ${platform}-${arch}. Ensure the correct optional dependency is installed.

What it means

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.

Solutions

1. Reinstall dependencies with optional deps enabled: `npm install` (avoid `--omit=optional`).
2. Verify the matching package exists in node_modules, e.g. `ls node_modules/@liteparse/liteparse-linux-x64-gnu`, and reinstall if absent.
3. Confirm the runtime platform/arch is supported (`node -p "process.platform + '-' + process.arch"`) and matches a published prebuild.
4. In Docker, don't delete platform packages in the final stage; use `npm ci` with default settings.
5. If on an unsupported platform, build the native crate from source or use a supported base image (e.g. debian instead of alpine).

Example fix

// before (Dockerfile)
RUN npm ci --omit=optional
// after
RUN npm ci

import { createRequire } from 'module';
const req = createRequire(import.meta.url);
const pkg = `@liteparse/liteparse-${process.platform}-${process.arch}`;
let ok = false;
try { req.resolve(pkg); ok = true; } catch {}
if (!ok) console.error(`Native package ${pkg} is not installed — reinstall without --omit=optional`);

const hasNative = () => {
  try { require.resolve(`@liteparse/liteparse-${process.platform}-${process.arch}`); return true; }
  catch { return false; }
};

let lp;
try {
  lp = new LiteParse();
} catch (e) {
  if (e.message.startsWith('Failed to load native module')) {
    console.error('Native binary missing. Run: npm install (with optional deps enabled).');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: `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.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• parseTimeoutMs requires poolSize

AI-assisted analysis of run-llama/liteparse@22d2dd8cd7 (2026-09-08). Data as JSON: /api/errors/039320c168aa7bcb. Report an issue: GitHub.

Appendix: source

Thrown at packages/node/src/native.ts:433

  // Try several paths since __dirname may be dist/ or dist/src/
  const searchDirs = [__dirname, join(__dirname, ".."), join(__dirname, "..", "..")];
  // Try full triple names (e.g. liteparse.linux-x64-gnu.node) and simple name
  const fileNames = [
    ...candidates.map((c) => `liteparse.${c}.node`),
    `liteparse.${platform}-${arch}.node`,
    "liteparse.node",
  ];
  for (const dir of searchDirs) {
    for (const fileName of fileNames) {
      try {
        return require(join(dir, fileName));
      } catch {
        // try next
      }
    }
  }

  throw new Error(
    `Failed to load native module for ${platform}-${arch}. ` +
      `Ensure the correct optional dependency is installed.`,
  );
}

export const native = loadNative();

View on GitHub (pinned to 22d2dd8cd7)