withastro/astro · error · Error

`workerd` does not run on Stackblitz.

Error message

`workerd` does not run on Stackblitz.

What it means

Thrown by `@astrojs/cloudflare` during `astro:config:setup` when the runtime is detected as a Stackblitz WebContainer (`process.versions.webcontainer` is set). Cloudflare's local runtime `workerd` is incompatible with WebContainer's emulated environment, so the integration refuses to initialize rather than failing opaquely later.

Source

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

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

Solutions

1. Develop locally (native Node) instead of Stackblitz when using the Cloudflare adapter.
2. Temporarily remove or disable `@astrojs/cloudflare` from adapters while on Stackblitz, then re-enable locally.
3. Use the Node adapter (`@astrojs/node`) for Stackblitz-based development.

Example fix

// before — astro.config.mjs on Stackblitz
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ adapter: cloudflare() });

// after — swap to node adapter for Stackblitz
import node from '@astrojs/node';
export default defineConfig({ adapter: node({ mode: 'standalone' }) });

// Detect Stackblitz/WebContainer before configuring the adapter.
if (process.versions.webcontainer) {
  console.warn('Cloudflare adapter unsupported on Stackblitz; use @astrojs/node.');
}

function isWebContainer(): boolean {
  return Boolean((process.versions as any).webcontainer);
}

When it happens

Trigger: Running `astro dev` or `astro build` with `@astrojs/cloudflare` adapter inside a Stackblitz or Codeflow project. The check `!!process.versions.webcontainer` is true, triggering the throw before any adapter setup.

Common situations: Opening an Astro+Cloudflare project on stackblitz.com. Using GitHub Codespaces with a WebContainer-backed preview. The adapter is installed but the user is prototyping on Stackblitz.

Related errors

• MissingSharp
• Integration "${maybeConflictingIntegration}" conflicts with
• AdapterSupportOutputMismatch
• ClientAddressNotAvailable
• StaticClientAddressNotAvailable

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