withastro/astro · error · AstroError

MissingSharp

MissingSharp

Error message

Could not find Sharp. Please install Sharp (`sharp`) manually into your project or migrate to another image service.

What it means

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.

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

Example fix

```bash
# before: MissingSharp during build
astro build

# after
npm install sharp
astro build
```

Defensive patterns

Strategy: validation

Validate before calling

// run before build (e.g. prebuild script)
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
try {
  require.resolve('sharp');
  console.log('sharp ok');
} catch {
  console.error('sharp is not installed — run: npm install sharp');
  process.exit(1);
}

Try / catch

try {
  const img = await getImage({ src });
} catch (err) {
  if (err instanceof AstroError && err.code === 'MissingSharp') {
    // fall back to rendering the original URL without optimization
    return { src: typeof src === 'string' ? src : src.src };
  }
  throw err;
}

Prevention

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

When it happens

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

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

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

AI-assisted analysis of withastro/astro@e294953aa8 (2026-08-18). Data as JSON: /api/errors/0f3290b357a9ec5b. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/assets/services/sharp.ts:123

			}
			return webpOptions;
		}
		case 'avif':
			return {
				...serviceConfig.avif,
				...(quality === undefined ? {} : { quality }),
			};
		default:
			return quality === undefined ? undefined : { quality };
	}
}

async function loadSharp(): Promise<SharpConstructor> {
	let sharpImport: SharpConstructor;
	try {
		sharpImport = (await import('sharp')).default;
	} catch {
		throw new AstroError(AstroErrorData.MissingSharp);
	}

	// 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
	sharpImport.cache(false);

	return sharpImport;
}

const fitMap: Record<ImageFit, keyof FitEnum> = {
	fill: 'fill',
	contain: 'inside',
	cover: 'cover',
	none: 'outside',
	'scale-down': 'inside',
	outside: 'outside',
	inside: 'inside',
};

View on GitHub (pinned to e294953aa8)