withastro/astro · error · Error

`workerd` does not run on Stackblitz.

Error message

`workerd` does not run on Stackblitz.

What it means

The @astrojs/cloudflare adapter needs to run the workerd binary to emulate Cloudflare's runtime, and workered cannot execute inside StackBlitz's WebContainer (browser-based Node emulation). At astro:config:setup the adapter checks `process.versions.webcontainer` and aborts immediately with this message. It is an intentional environment guard, not a bug.

Solutions

1. Open the same repository locally (`git clone` + `npm install`) or in a real VM environment such as GitHub Codespaces / Gitpod.
2. If you only need a UI preview in StackBlitz, temporarily remove the cloudflare adapter from astro.config.mjs and use static output.
3. Use Cloudflare's own browser-based Workers playground to test worker code instead of StackBlitz.

Example fix

// before (astro.config.mjs)
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ output: 'server', adapter: cloudflare() });

// after — for StackBlitz preview only
export default defineConfig({ output: 'static' });

// astro.config.mjs — choose adapter only when workerd can actually run
const inWebContainer = !!process.versions.webcontainer;
export default defineConfig({
  adapter: inWebContainer ? undefined : cloudflare(),
  output: inWebContainer ? 'static' : 'server',
});

When it happens

Trigger: Opening an Astro project configured with the @astrojs/cloudflare adapter inside stackblitz.com (or any WebContainer-based environment) and running `astro dev` or `astro build`.

Common situations: Clicking a Cloudflare template on StackBlitz instead of running locally; trying to demo or teach an Astro + Cloudflare app in a browser playground; moving a project into a WebContainer-based IDE.

Related errors

• AdapterSupportOutputMismatch
• Astro.locals.runtime.caches has been removed in Astro v6…
• Astro.locals.runtime.cf has been removed in Astro v6. Use…
• Astro.locals.runtime.ctx has been removed in Astro v6. Use…
• Astro.locals.runtime.env has been removed in Astro v6. Use…

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

Appendix: source

Thrown at packages/integrations/cloudflare/src/index.ts:163

	let _routes: IntegrationResolvedRoute[];
	let cfPluginConfig: PluginConfig;
	let hasUserBuildImageService = false;
	let compileImageConfig: CompileImageConfig | null = null;

	const { buildService, runtimeService, transformAtBuild } =
		normalizeImageServiceConfig(imageService);
	const needsImagesBinding = runtimeService === 'cloudflare-binding';
	const hasBuildImageService = buildService === 'compile' || buildService === 'custom';
	// Opt-in: user explicitly requested build-time image transformation via the compound config.
	// The string shorthand `'cloudflare-binding'` keeps the historical runtime-only behavior.
	const isBindingBuild = transformAtBuild && buildService === 'cloudflare-binding';

	return {
		name: '@astrojs/cloudflare',
		hooks: {
			'astro:config:setup': async ({ command, config, updateConfig, logger, addWatchFile }) => {
				if (!!process.versions.webcontainer) {
					throw new Error('`workerd` does not run on Stackblitz.');
				}

				let session = config.session;
				const isCompile = buildService === 'compile';

				if (needsImagesBinding) {
					logger.info(
						`Enabling image processing with Cloudflare Images for production with the "${imagesBindingName}" Images binding.`,
					);
				} else if (hasBuildImageService) {
					logger.info(
						`Enabling compile-time image optimization. Images will be pre-optimized at build time.`,
					);
				}

				if (session !== false && !session?.driver) {
					logger.info(
						`Enabling sessions with Cloudflare KV with the "${sessionKVBindingName}" KV binding.`,

View on GitHub (pinned to e294953aa8)