withastro/astro · warning

The Sharp image service cannot run inside the workerd runtim

Error message

The Sharp image service cannot run inside the workerd runtime, so '/_image' requests will fail in dev and production. Configure a workerd-compatible 'image.service', or set 'imageService' to 'compile' for build-time optimization. See https://docs.astro.build/en/guides/integrations-guide/cloudflare/#imageservice

What it means

The Cloudflare adapter rewrites the image config for the workerd runtime. In the 'custom' imageService case during `astro dev`, if the resolved service is still Astro's default Sharp service, it warns: Sharp's native binding cannot load inside workerd, so /_image requests will fail both in the dev preview and in production on Workers. The same branch also catches imageService 'custom' with no service configured (which silently inherits Sharp).

Source

Thrown at packages/integrations/cloudflare/src/utils/image-config.ts:138

			// Dev: IMAGES binding (via Cloudflare Vite plugin) for real transforms.
			// Build: endpoint depends on runtime - `cloudflare-binding` uses IMAGES, `passthrough` uses generic.
			const endpoint =
				command === 'dev' || runtimeService === 'cloudflare-binding'
					? { entrypoint: '@astrojs/cloudflare/image-transform-endpoint' }
					: CLOUDFLARE_PASSTHROUGH_ENDPOINT;
			return {
				...config,
				service: hasUserImageService(config) ? config.service : WORKERD_IMAGE_SERVICE,
				endpoint,
			};
		}

		case 'custom':
			// Sharp's native binding cannot load inside workerd, in dev or in production.
			// This also catches `imageService: 'custom'` without a configured `image.service`,
			// which silently inherits Astro's default Sharp service.
			if (command === 'dev' && config.service.entrypoint === SHARP_IMAGE_SERVICE) {
				logger.warn(
					`The Sharp image service cannot run inside the workerd runtime, so '/_image' requests will fail in dev and production. Configure a workerd-compatible 'image.service', or set 'imageService' to 'compile' for build-time optimization. See https://docs.astro.build/en/guides/integrations-guide/cloudflare/#imageservice`,
				);
			}
			return {
				...config,
				// Astro's default dev endpoint imports `vite` and `node:fs`, which are
				// unavailable in workerd. Use the generic (fetch-based) endpoint instead.
				...(command === 'dev' && !config.endpoint?.entrypoint && { endpoint: GENERIC_ENDPOINT }),
			};

		default:
			if (config.service.entrypoint === 'astro/assets/services/sharp') {
				logger.warn(
					`The current configuration does not support image optimization. To allow your project to build with the original, unoptimized images, the image service has been automatically switched to the 'passthrough' option. See https://docs.astro.build/en/reference/configuration-reference/#imageservice`,
				);
				return {
					...config,
					service: passthroughImageService(),

View on GitHub (pinned to 52e6c34790)

Solutions

1. Set the adapter's imageService option to 'compile' so images are optimized at build time
2. Or configure a workerd-compatible image.service entrypoint (fetch-based) in astro.config
3. Or choose 'passthrough' if serving original, unoptimized images is acceptable
4. Verify /_image works in the workerd dev preview after changing the config

Example fix

// before
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ integrations: [cloudflare()] }); // inherits Sharp -> warning

// after
export default defineConfig({
  integrations: [cloudflare({ imageService: 'compile' })],
});

// astro.config.mjs — decide the image strategy explicitly when using the adapter
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
  integrations: [cloudflare({ imageService: 'compile' })], // or 'passthrough'
});

When it happens

Trigger: Using @astrojs/cloudflare with imageService unset/'custom' while running `astro dev`: any <Image /> or getImage() call whose /_image request goes through the workerd dev runtime fails, because the Sharp native module cannot be loaded there.

Common situations: Adopting the Cloudflare adapter on a project that previously optimized images locally with Sharp; upgrading the adapter, which began validating image services against workerd and warning instead of failing at runtime.

Related errors

• The current configuration does not support image optimizatio
• ⚠️ Astro expected an SVG for "${transform.src}" but the sou
• ⚠️ Astro could not optimize image "${transform.src}". Sharp
• Language does not exist: ${lang}
• MissingSharp

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