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

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.

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 d081033d5f)

Solutions

1. Install sharp directly: npm install sharp (or pnpm add sharp).
2. On Alpine/musl install the musl variant or switch to a glibc base image.
3. Ensure your Node architecture has a prebuilt sharp; rebuild native deps (npm rebuild sharp).
4. Migrate to a non-sharp image service (e.g. a passthrough/external service) if sharp cannot run.
5. Verify libvips is present on the system if using a system-vips build.

Example fix

// before - sharp missing
// (build fails with MissingSharp)

// after
// package.json: add sharp as a dependency
// then run: pnpm install

async function sharpAvailable(): Promise<boolean> {
  try { await import('sharp'); return true; } catch { return false; }
}

try { await import('sharp'); }
catch (e) {
  if (e instanceof AstroError && e.code === 'MissingSharp') {
    // install sharp or switch to a non-sharp service in astro.config
  }
}

When it happens

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

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

Related errors

• NoImageMetadata
• UnsupportedImageFormat
• ExpectedImageOptions
• ExpectedImage
• ExpectedNotESMImage

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