{"record":{"id":"0f3290b357a9ec5b","repo":"withastro/astro","slug":"missingsharp","errorCode":"MissingSharp","errorMessage":"Could not find Sharp. Please install Sharp (`sharp`) manually into your project or migrate to another image service.","messagePattern":"Could not find Sharp\\. Please install Sharp \\(`sharp`\\) manually into your project or migrate to another image service\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/services/sharp.ts","lineNumber":123,"sourceCode":"\t\t\t}\n\t\t\treturn webpOptions;\n\t\t}\n\t\tcase 'avif':\n\t\t\treturn {\n\t\t\t\t...serviceConfig.avif,\n\t\t\t\t...(quality === undefined ? {} : { quality }),\n\t\t\t};\n\t\tdefault:\n\t\t\treturn quality === undefined ? undefined : { quality };\n\t}\n}\n\nasync function loadSharp(): Promise<SharpConstructor> {\n\tlet sharpImport: SharpConstructor;\n\ttry {\n\t\tsharpImport = (await import('sharp')).default;\n\t} catch {\n\t\tthrow new AstroError(AstroErrorData.MissingSharp);\n\t}\n\n\t// Disable the `sharp` `libvips` cache as it errors when the file is too small and operations are happening too fast (runs into a race condition) https://github.com/lovell/sharp/issues/3935#issuecomment-1881866341\n\tsharpImport.cache(false);\n\n\treturn sharpImport;\n}\n\nconst fitMap: Record<ImageFit, keyof FitEnum> = {\n\tfill: 'fill',\n\tcontain: 'inside',\n\tcover: 'cover',\n\tnone: 'outside',\n\t'scale-down': 'inside',\n\toutside: 'outside',\n\tinside: 'inside',\n};\n","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/assets/services/sharp.ts#L105-L141","documentation":"Astro's default image service is backed by Sharp, but Sharp is an optional native dependency you must install yourself. `loadSharp()` in packages/astro/src/assets/services/sharp.ts does `await import('sharp')` and throws MissingSharp when the import fails, so any image transform at build or render time fails until Sharp is resolvable from your project.","triggerScenarios":"Running `astro build`/`astro dev` with `<Image>`, `<Picture>`, or `getImage()` while `sharp` is not in node_modules (or its native binaries failed to install). Also happens in minimal Docker images, pnpm strict node_modules, or when a lockfile update dropped sharp.","commonSituations":"Fresh project scaffolded before sharp became an explicit peer install; CI cache restored without native modules; Node version mismatch breaking sharp's prebuilt binaries; monorepo hoisting so sharp resolves in dev but not in the app package.","solutions":["Run `npx astro add sharp` or install it directly: `npm install sharp` (pnpm/yarn equivalent) and commit the lockfile","Verify resolution from the app directory: `node -e \"import('sharp').then(() => console.log('ok'))\"`; reinstall with `npm rebuild sharp` or delete node_modules + lockfile install if binaries are broken","If you cannot use native modules, switch the image service in astro.config.mjs: `image: { service: { entrypoint: 'astro/assets/services/noop' } }` or a custom service"],"exampleFix":"```bash\n# before: MissingSharp during build\nastro build\n\n# after\nnpm install sharp\nastro build\n```","handlingStrategy":"validation","validationCode":"// run before build (e.g. prebuild script)\nimport { createRequire } from 'node:module';\nconst require = createRequire(import.meta.url);\ntry {\n  require.resolve('sharp');\n  console.log('sharp ok');\n} catch {\n  console.error('sharp is not installed — run: npm install sharp');\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const img = await getImage({ src });\n} catch (err) {\n  if (err instanceof AstroError && err.code === 'MissingSharp') {\n    // fall back to rendering the original URL without optimization\n    return { src: typeof src === 'string' ? src : src.src };\n  }\n  throw err;\n}","preventionTips":["Add sharp to dependencies (not devDependencies) of the deploying app","Include a sharp resolution check in CI before astro build","Pin a sharp major known to match your Node version"],"tags":["astro","images","sharp","native-modules","dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}