@astrojs/cloudflare: `/_image` requests break when catch-all routes are combined with `prerenderEnvironment: 'node'``

[kitschpatrol]

Astro Info

Astro                    v7.0.7
Node                     v26.4.0
System                   macOS (arm64)
Package Manager          pnpm
Output                   static
Adapter                  @astrojs/cloudflare
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

With the Cloudflare adapter configured with prerenderEnvironment: 'node', adding a prerendered catch-all route (src/pages/[...slug].astro) makes every image served through the /_image endpoint return a 500 in astro dev:

[ERROR] Could not import `cloudflare:workers`.
  Error reference:
    https://docs.astro.build/en/reference/errors/failed-to-load-module-ssr/
  Location:
    @astrojs/cloudflare/dist/entrypoints/image-transform-endpoint.js:1:21

Only two ingredients are needed, both in this repo's default config:

1. prerenderEnvironment: 'node' in the adapter options.
2. A prerendered catch-all route. Its pattern matches every pathname, including /_image.

The default image service (cloudflare-binding) is already affected — no imageService option is required.

This breaks Starlight. Starlight injects exactly such a route (@astrojs/starlight/routes/static/index.astro, a prerendered /[...slug] catch-all), so any Starlight site using the Cloudflare adapter with prerenderEnvironment: 'node' has every dev-mode image 500 this way. The [...slug].astro in this repo is just a dependency-free stand-in for Starlight's route.

Steps to Reproduce

Clone https://github.com/kitschpatrol/repro-astro-cloudflare-image-dev-error

pnpm install
pnpm dev

Open http://localhost:4321/ — the image is broken. Requesting its /_image URL directly returns a 500 with FailedToLoadModuleSSR.

Then delete src/pages/[...slug].astro and request the same URL: 200, image/webp.

Workaround

Skip the cloudflare:workers-based image endpoint in dev:

const isDev = process.argv.includes("dev");

adapter: cloudflare({
  prerenderEnvironment: "node",
  imageService: isDev ? "passthrough" : "cloudflare-binding",
}),

What's the expected result?

/_image requests in dev return the transformed image (200, image/webp), as they do when either ingredient is removed:

• Delete src/pages/[...slug].astro → image works.
• Remove prerenderEnvironment: 'node' → image works.

Link to Minimal Reproducible Example

https://github.com/kitschpatrol/repro-astro-cloudflare-image-dev-error

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: Yes
• Exploration: Yes — View branch
• Unit Test: No — existing cloudflare adapter tests (dev-image-endpoint.test.ts, prerender-node-env.test.ts) all pass; a dedicated test would require a fixture combining both prerenderEnvironment: 'node' and a catch-all route with the cloudflare image endpoint.
• Priority: P4: important. This breaks all image optimization in astro dev for any Cloudflare + prerenderEnvironment: 'node' project that has a prerendered catch-all route — which includes every Starlight site on Cloudflare. A workaround exists (switching to passthrough image service in dev), but the default configuration is broken.

The root cause is in packages/astro/src/core/routing/dev.ts: when the prerender middleware handles a /_image request, matchRoute eagerly imports every matching route's component module — including the non-prerendered /_image endpoint — before checking whether the route is actually prerendered. The /_image endpoint (@astrojs/cloudflare/image-transform-endpoint) imports cloudflare:workers at the top level, which doesn't exist in the Node prerender environment, causing the 500. The catch-all [...slug] route is needed because it's what causes matchAllRoutes to include a prerendered match for the /_image path, which trips the broad prerender gate in plugin.ts.

I found a potential fix for this issue. The fix threads the existing prerenderOnly flag from handleRequest through devMatch into matchRoute, which now skips routes with prerender: false before attempting to import their components. This prevents the Node prerender environment from ever trying to load modules that require runtime-specific APIs like cloudflare:workers.

Try this fix

You can test this fix right now without waiting for a release:

npm i https://pkg.pr.new/astro@5ce4db5

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Reproduction

Created a minimal project with:

• @astrojs/cloudflare adapter with prerenderEnvironment: 'node'
• A prerendered catch-all route src/pages/[...slug].astro with export const prerender = true
• A page using <Image> from astro:assets

Requesting /_image returned HTTP 500 with FailedToLoadModuleSSR: Could not import cloudflare:workers. Removing the catch-all route made the same request return HTTP 200.

Diagnosis

The request flow for /_image with both conditions present:

1. Broad prerender gate (packages/astro/src/vite-plugin-astro-server/plugin.ts): matchAllRoutes('/_image') returns both the /_image endpoint (prerender: false) and [...slug] (prerender: true). Since .some(r => r.prerender) is true, the prerender handler is invoked.

2. Eager component import (packages/astro/src/core/routing/dev.ts): matchRoute iterates sorted candidates. /_image has higher route priority than the catch-all, so it's tried first. pipeline.getComponentByRoute() imports @astrojs/cloudflare/image-transform-endpoint in the Node environment. This module has import { env } from 'cloudflare:workers' at the top level — which fails in Node.

3. Error stored and re-thrown: The import error is not a NoMatchingStaticPathFound, so it's stored as firstError. The catch-all's getStaticPaths() doesn't include _image, so it throws NoMatchingStaticPathFound (caught and skipped). With all candidates exhausted, firstError is thrown → 500 response.

The existing prerenderOnly check in handleRequest (line ~217 of app.ts) happens after devMatch returns, but the crash occurs inside devMatch during the component import.

This is the same class of bug as #16562 and #16747, which both involved the prerender handler doing work on non-prerendered routes before filtering them out.

Fix

Files changed:

• packages/astro/src/core/routing/dev.ts — Added prerenderOnly option to matchRoute; skips non-prerendered routes before importing their components.
• packages/astro/src/vite-plugin-app/app.ts — Threaded prerenderOnly from handleRequest through devMatch to matchRoute.

All existing tests pass: dev-image-endpoint.test.ts (6/6), prerender-node-env.test.ts (7/7), routing unit tests.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[kitschpatrol]

@astrobot-houston seems like a fix

[astrobot-houston]

The fix has been verified! A pull request has been created: #17349