{"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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/assets/services/sharp.ts#L105-L141","documentation":"Thrown by the sharp service's loadSharp() when `await import('sharp')` rejects. Sharp is an optional native dependency; if it cannot be resolved or loaded (not installed, native binary missing, incompatible arch/libvips), MissingSharp is thrown with no cause.","triggerScenarios":"Selecting the sharp image service (the default) in an environment where the `sharp` package fails to import — e.g. not installed as a direct dependency, musl-vs-glibc mismatch on Linux, missing libvips, arm64/x64 binary mismatch, or a bundler that strips the native require.","commonSituations":"Fresh project where sharp wasn't installed, deploying to an Alpine/musl image without the musl sharp binary, a Node arch with no prebuilt sharp, or a package manager that hoisted sharp away from the consumer.","solutions":["Install sharp directly: npm install sharp (or pnpm add sharp).","On Alpine/musl install the musl variant or switch to a glibc base image.","Ensure your Node architecture has a prebuilt sharp; rebuild native deps (npm rebuild sharp).","Migrate to a non-sharp image service (e.g. a passthrough/external service) if sharp cannot run.","Verify libvips is present on the system if using a system-vips build."],"exampleFix":"// before - sharp missing\n// (build fails with MissingSharp)\n\n// after\n// package.json: add sharp as a dependency\n// then run: pnpm install","handlingStrategy":"try-catch","validationCode":"async function sharpAvailable(): Promise<boolean> {\n  try { await import('sharp'); return true; } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try { await import('sharp'); }\ncatch (e) {\n  if (e instanceof AstroError && e.code === 'MissingSharp') {\n    // install sharp or switch to a non-sharp service in astro.config\n  }\n}","preventionTips":["Install sharp as a direct dependency in every project using the default service.","Use a glibc base image or the musl sharp variant on Alpine.","Verify the Node architecture has a prebuilt sharp; rebuild native modules on deploy."],"tags":["images","sharp","native-modules","environment"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}