{"record":{"id":"f1bb786491203a6c","repo":"withastro/astro","slug":"the-sharp-image-service-cannot-run-inside-the-work","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/integrations/cloudflare/src/utils/image-config.ts","lineNumber":138,"sourceCode":"\t\t\t// Dev: IMAGES binding (via Cloudflare Vite plugin) for real transforms.\n\t\t\t// Build: endpoint depends on runtime - `cloudflare-binding` uses IMAGES, `passthrough` uses generic.\n\t\t\tconst endpoint =\n\t\t\t\tcommand === 'dev' || runtimeService === 'cloudflare-binding'\n\t\t\t\t\t? { entrypoint: '@astrojs/cloudflare/image-transform-endpoint' }\n\t\t\t\t\t: CLOUDFLARE_PASSTHROUGH_ENDPOINT;\n\t\t\treturn {\n\t\t\t\t...config,\n\t\t\t\tservice: hasUserImageService(config) ? config.service : WORKERD_IMAGE_SERVICE,\n\t\t\t\tendpoint,\n\t\t\t};\n\t\t}\n\n\t\tcase 'custom':\n\t\t\t// Sharp's native binding cannot load inside workerd, in dev or in production.\n\t\t\t// This also catches `imageService: 'custom'` without a configured `image.service`,\n\t\t\t// which silently inherits Astro's default Sharp service.\n\t\t\tif (command === 'dev' && config.service.entrypoint === SHARP_IMAGE_SERVICE) {\n\t\t\t\tlogger.warn(\n\t\t\t\t\t`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`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn {\n\t\t\t\t...config,\n\t\t\t\t// Astro's default dev endpoint imports `vite` and `node:fs`, which are\n\t\t\t\t// unavailable in workerd. Use the generic (fetch-based) endpoint instead.\n\t\t\t\t...(command === 'dev' && !config.endpoint?.entrypoint && { endpoint: GENERIC_ENDPOINT }),\n\t\t\t};\n\n\t\tdefault:\n\t\t\tif (config.service.entrypoint === 'astro/assets/services/sharp') {\n\t\t\t\tlogger.warn(\n\t\t\t\t\t`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`,\n\t\t\t\t);\n\t\t\t\treturn {\n\t\t\t\t\t...config,\n\t\t\t\t\tservice: passthroughImageService(),","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/integrations/cloudflare/src/utils/image-config.ts#L120-L156","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the adapter's imageService option to 'compile' so images are optimized at build time","Or configure a workerd-compatible image.service entrypoint (fetch-based) in astro.config","Or choose 'passthrough' if serving original, unoptimized images is acceptable","Verify /_image works in the workerd dev preview after changing the config"],"exampleFix":"// before\nimport cloudflare from '@astrojs/cloudflare';\nexport default defineConfig({ integrations: [cloudflare()] }); // inherits Sharp -> warning\n\n// after\nexport default defineConfig({\n  integrations: [cloudflare({ imageService: 'compile' })],\n});","handlingStrategy":"validation","validationCode":"// astro.config.mjs — decide the image strategy explicitly when using the adapter\nimport cloudflare from '@astrojs/cloudflare';\nexport default defineConfig({\n  integrations: [cloudflare({ imageService: 'compile' })], // or 'passthrough'\n});","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never rely on the inherited default image service with edge adapters — set imageService explicitly","Smoke-test /_image in the workerd dev preview after any adapter config change","Re-read the adapter's images documentation when upgrading @astrojs/cloudflare"],"tags":["cloudflare","images","sharp","workerd","native-module"],"backgroundTag":"native-module-in-edge-runtime","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}