lovell/sharp · critical · Error

help.join("\n")

Error message

help.join("\n")

What it means

This is not a logic error — it is the final throw inside sharp's native-module load helper. When the prebuilt libvips-backed native binary (@img/sharp-*) fails to load, sharp collects a list of platform/installation diagnostics into the `help` array and throws it joined by newlines. The thrown message is the assembled multi-line troubleshooting guide; the actual underlying cause (DLL missing, glibc/musl mismatch, wrong CPU arch, --no-addons, outdated sharp in the tree, etc.) is embedded in that text. Hitting it means sharp could not initialize its native addon at all, so no image processing will work.

Solutions

1. Read the full thrown message — it names the exact load failure (symbol, arch, libc) and prints tailored next steps.
2. Reinstall with optional deps: npm install --include=optional sharp (or yarn add sharp, pnpm add sharp).
3. Install the exact platform package: npm install --os=<os> --cpu=<cpu> sharp (e.g., --os=linux --cpu=x64).
4. For musl/Alpine, ensure the musl build is fetched or use a glibc-based image.
5. Remove Node.js Snap on Linux (snap remove node) and use an official Node build.
6. On macOS with Homebrew libvips issues: brew update && brew upgrade vips.
7. On Windows with canvas conflicts, follow the documented canvas-and-windows section and run npm ls sharp to find stale versions.
8. For globally-installed libvips, install libvips >= the minimum version sharp reports.
9. If running Node with --no-addons, remove that flag.

Example fix

// before: throws on import in a musl Alpine container with only glibc binary
import sharp from 'sharp';

// after: install the correct platform binary, then import works
//   Dockerfile:
//   RUN npm install --os=linux --libc=musl --cpu=x64 sharp
import sharp from 'sharp';

// Validate the environment matches a known-good platform package before importing sharp.
function preflightSharp() {
  const { arch, platform } = process;
  const libc = (() => { try { const { familySync } = require('detect-libc'); return familySync(); } catch { return 'glibc'; } })();
  if (process.execArgv.includes('--no-addons')) {
    throw new Error('sharp requires native addons; remove --no-addons');
  }
  console.log(`preflight: arch=${arch} platform=${platform} libc=${libc}`);
}
preflightSharp();

let sharp;
try {
  sharp = require('sharp');
} catch (err) {
  // err.message is the assembled multi-line install help; surface it to ops, fail fast.
  console.error('sharp failed to load native binary:', err.message);
  throw err;
}

When it happens

Trigger: First require/import of sharp on a machine where the platform-specific optional dependency was not installed (npm install without --include=optional or a registry that filtered optionals). Running on an unsupported CPU arch or libc (e.g., musl image but glibc binary fetched). A Node.js started with --no-addons (ERR_DLOPEN_DISABLED). Stale/incompatible libvips on Linux (symbol not found / CXXABI errors). Windows canvas/old-sharp DLL conflict. macOS incompatible Homebrew libvips version.

Common situations: Docker images (especially Alpine/musl) missing the right @img/sharp-linux-x64 musl variant. CI that runs npm ci with --omit=optional. Deploying a node_modules built on one OS/arch to another. Lockfile or bundledDependencies pulling an outdated sharp version. Snap-packaged Node.js on Linux (no native module support). Electron apps bundling sharp without rebuild.

AI-assisted analysis of lovell/sharp@56676c6918 (2026-08-13). Data as JSON: /api/errors/9ce709cae13a7221. Report an issue: GitHub.

Appendix: source

Thrown at lib/sharp.mjs:171

    help.push("- Remove the Node.js Snap, which does not support native modules", "    snap remove node");
  }
  if (isMacOs && /Incompatible library version/.test(messages)) {
    help.push("- Update Homebrew:", "    brew update && brew upgrade vips");
  }
  if (errors.some((err) => err.code === "ERR_DLOPEN_DISABLED")) {
    help.push("- Run Node.js without using the --no-addons flag");
  }
  // Link to installation docs
  if (isWindows && /The specified procedure could not be found/.test(messages)) {
    help.push(
      "- Using the canvas package on Windows?",
      "    See https://sharp.pixelplumbing.com/install#canvas-and-windows",
      "- Check for outdated versions of sharp in the dependency tree:",
      "    npm ls sharp",
    );
  }
  help.push("- Consult the installation documentation:", "    See https://sharp.pixelplumbing.com/install");
  throw new Error(help.join("\n"));
}

export default sharp;

View on GitHub (pinned to 56676c6918)