{"record":{"id":"9ce709cae13a7221","repo":"lovell/sharp","slug":"help-join-n","errorCode":null,"errorMessage":"help.join(\"\\n\")","messagePattern":"help\\.join\\(\"\\\\n\"\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"lib/sharp.mjs","lineNumber":171,"sourceCode":"    help.push(\"- Remove the Node.js Snap, which does not support native modules\", \"    snap remove node\");\n  }\n  if (isMacOs && /Incompatible library version/.test(messages)) {\n    help.push(\"- Update Homebrew:\", \"    brew update && brew upgrade vips\");\n  }\n  if (errors.some((err) => err.code === \"ERR_DLOPEN_DISABLED\")) {\n    help.push(\"- Run Node.js without using the --no-addons flag\");\n  }\n  // Link to installation docs\n  if (isWindows && /The specified procedure could not be found/.test(messages)) {\n    help.push(\n      \"- Using the canvas package on Windows?\",\n      \"    See https://sharp.pixelplumbing.com/install#canvas-and-windows\",\n      \"- Check for outdated versions of sharp in the dependency tree:\",\n      \"    npm ls sharp\",\n    );\n  }\n  help.push(\"- Consult the installation documentation:\", \"    See https://sharp.pixelplumbing.com/install\");\n  throw new Error(help.join(\"\\n\"));\n}\n\nexport default sharp;\n","sourceCodeStart":153,"sourceCodeEnd":175,"githubUrl":"https://github.com/lovell/sharp/blob/56676c69180a32b468123e090f87bfee30539b49/lib/sharp.mjs#L153-L175","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the full thrown message — it names the exact load failure (symbol, arch, libc) and prints tailored next steps.","Reinstall with optional deps: npm install --include=optional sharp (or yarn add sharp, pnpm add sharp).","Install the exact platform package: npm install --os=<os> --cpu=<cpu> sharp (e.g., --os=linux --cpu=x64).","For musl/Alpine, ensure the musl build is fetched or use a glibc-based image.","Remove Node.js Snap on Linux (snap remove node) and use an official Node build.","On macOS with Homebrew libvips issues: brew update && brew upgrade vips.","On Windows with canvas conflicts, follow the documented canvas-and-windows section and run npm ls sharp to find stale versions.","For globally-installed libvips, install libvips >= the minimum version sharp reports.","If running Node with --no-addons, remove that flag."],"exampleFix":"// before: throws on import in a musl Alpine container with only glibc binary\nimport sharp from 'sharp';\n\n// after: install the correct platform binary, then import works\n//   Dockerfile:\n//   RUN npm install --os=linux --libc=musl --cpu=x64 sharp\nimport sharp from 'sharp';","handlingStrategy":"try-catch","validationCode":"// Validate the environment matches a known-good platform package before importing sharp.\nfunction preflightSharp() {\n  const { arch, platform } = process;\n  const libc = (() => { try { const { familySync } = require('detect-libc'); return familySync(); } catch { return 'glibc'; } })();\n  if (process.execArgv.includes('--no-addons')) {\n    throw new Error('sharp requires native addons; remove --no-addons');\n  }\n  console.log(`preflight: arch=${arch} platform=${platform} libc=${libc}`);\n}\npreflightSharp();","typeGuard":null,"tryCatchPattern":"let sharp;\ntry {\n  sharp = require('sharp');\n} catch (err) {\n  // err.message is the assembled multi-line install help; surface it to ops, fail fast.\n  console.error('sharp failed to load native binary:', err.message);\n  throw err;\n}","preventionTips":["Install with optional dependencies enabled (npm install --include=optional sharp).","Pin and verify the @img/sharp-<platform>-<arch> package in node_modules for your runtime.","In Docker, match the base image libc (musl vs glibc) to the sharp binary variant or install the explicit --os/--cpu/--libc package.","Do not run Node with --no-addons in environments that use sharp.","Run npm ls sharp to detect stale versions in the dependency tree.","On Linux, keep libvips >= sharp's minimum version if using a global libvips build.","Rebuild or reinstall sharp after major Node.js or OS upgrades."],"tags":["native-module","installation","platform","libvips","environment","load-failure"],"backgroundTag":null,"analyzedSha":"56676c69180a32b468123e090f87bfee30539b49","analyzedAt":"2026-08-13T04:44:31.201Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}