withastro/astro · warning

The current configuration does not support image optimizatio

Error message

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

What it means

Fallback branch of the Cloudflare adapter's image-config hook: when the resolved image service entrypoint is exactly 'astro/assets/services/sharp' (Astro's core default) and no earlier case matched, the adapter warns that this environment cannot optimize images, swaps the service to passthroughImageService(), and continues — the build succeeds but ships original, unoptimized images.

Source

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

		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(),
					...(command === 'dev' && !config.endpoint?.entrypoint && { endpoint: GENERIC_ENDPOINT }),
				};
			}
			return {
				...config,
				...(command === 'dev' && !config.endpoint?.entrypoint && { endpoint: GENERIC_ENDPOINT }),
			};
	}
}

View on GitHub (pinned to 52e6c34790)

Solutions

1. Make the strategy explicit: adapter option imageService: 'compile' to optimize at build time
2. Or deliberately use 'passthrough' and optimize at the CDN/edge layer instead
3. Or implement a workerd-compatible custom image.service referenced from config
4. After changing config, verify built output actually contains optimized assets

Example fix

// before
integrations: [cloudflare()] // adapter force-switches to passthrough; images unoptimized

// after
integrations: [cloudflare({ imageService: 'compile' })] // optimized at build time

// astro.config.mjs — explicit choice prevents the silent passthrough switch
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
  integrations: [cloudflare({ imageService: 'compile' })], // 'passthrough' if CDN optimizes
});

When it happens

Trigger: Building (or resolving config) with @astrojs/cloudflare while the image service still resolves to Sharp — i.e. imageService neither 'compile' nor an explicit workerd-compatible custom service — so the adapter silently downgrades optimization to passthrough.

Common situations: Newly deployed Cloudflare projects where page weight suddenly grows because images stopped being optimized; teams unaware the default Sharp service is incompatible with workerd and that the adapter substituted a no-op.

Related errors

• ⚠️ Astro could not optimize image "${transform.src}". Sharp
• The Sharp image service cannot run inside the workerd runtim
• ⚠️ Astro expected an SVG for "${transform.src}" but the sou
• MissingSharp
• NoImageMetadata

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