After moving an SPA from Pages to a Cloudflare Worker with single-page-application fallback, the browser's OAuth redirect to /auth/callback returns index.html and never reaches the Worker; why, and how do you fix it?
answer
- who sent this request
- the browser is navigating, not fetching
- a header that marks navigations
- a compatibility date from 2025
- name the server routes explicitly
basics
~20 sThe provider's redirect is a browser navigation carrying Sec-Fetch-Mode: navigate, and for compatibility dates from 2025-04-01 a navigation that misses is answered with the SPA fallback without invoking the Worker. List the route in run_worker_first, or finish the exchange from client-side code.
solid answer
~40 sAn OAuth provider sends the user back with a redirect, so the browser *navigates* to `/auth/callback` and attaches `Sec-Fetch-Mode: navigate`. `/auth/callback` is not a file. For compatibility dates from 2025-04-01, `assets_navigation_prefers_asset_serving` is on by default: with `not_found_handling` set, a navigation miss gets the fallback, here `index.html` with `200`, and the Worker is never invoked. Under Pages, Functions ran before assets, so the same code worked. The cleanest fix is `"run_worker_first": ["/auth/callback", "/api/*"]`, which routes those paths to the Worker even on navigation. Alternatives: the `assets_navigation_has_no_effect` flag, which bills every missed navigation, or a client-side callback page that posts the code to an API route.
go deeper
Recall that browsers send Sec-Fetch-Mode: navigate when loading a page or following a redirect, and that Workers static assets treats such requests specially.
Explain the three-step order for a miss when a script exists, why curl behaves differently from a browser, and which compatibility date turned the navigation preference on.
Diagnose from the clues, no invocation in logs and a 200 HTML response, then choose between route patterns, the opt-out flag and a client-side callback by their cost.
Make an inventory of navigable server routes part of every Pages-to-Workers migration, and own the run_worker_first list as reviewed config, not an afterthought.
## The symptom A team moves a single-page app and its API from Pages to one Worker with static assets. The config sets `assets.directory`, a `main` script and `"not_found_handling": "single-page-application"`. Everything works in the browser until sign-in: after the identity provider redirects to `https://app.example.com/auth/callback?code=...&state=...`, the user lands on the app shell and is not signed in. Workers Logs show no invocation for that path at all. Calling `/auth/callback` from `curl` *does* reach the Worker, which makes the bug look random. ## The mechanism The order a Worker with static assets uses for a request, from a compatibility date of 2025-04-01 onward: 1. A path matching a file is served as the file. 2. A miss that is a **navigation request** gets the `not_found_handling` fallback **without invoking the Worker**. 3. Any other miss invokes the Worker. A navigation request is one carrying the `Sec-Fetch-Mode: navigate` header, which browsers attach when the user loads a page, follows a link, or follows a redirect. An OAuth callback is exactly that: the provider answers with a redirect and the browser navigates. `curl` sends no such header, so it took path 3 and reached the code. Step 2 comes from the `assets_navigation_prefers_asset_serving` compatibility flag, on by default from 2025-04-01. It exists to cut cost: an SPA's reloads and deep links are navigations, and serving the shell for them needs no billable code. The flag only matters when `not_found_handling` is configured and `run_worker_first` is unset: with `true` it has no effect, and an array replaces the header test. Pages behaved differently because Pages Functions ran **ahead** of static assets by default; `_routes.json` and middleware were the tools to change that. Workers is asset-first, so a route that the browser navigates to needs explicit routing. The same trap catches any path a user can type or bookmark: navigating to `/api/me` in the address bar returns HTML, while the page's own `fetch("/api/me")` returns JSON. ## Reproducing it `wrangler dev` applies the same rules, so the difference shows up locally with two requests: ```console $ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" -H "Sec-Fetch-Mode: navigate" http://localhost:8787/api/me 200 text/html; charset=utf-8 $ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://localhost:8787/api/me 200 application/json ``` ## The fixes | Fix | Effect | Cost | | --- | --- | --- | | `run_worker_first: ["/auth/callback", "/api/*"]` | those paths always run the Worker; other misses still get the shell without code | only matched paths are billed | | `assets_navigation_has_no_effect` flag | every miss, navigation or not, invokes the Worker as before 2025-04-01 | every missed navigation is billed | | client-side callback page | the SPA reads `code` and `state` and calls an API route with `fetch()` | an extra round trip, no config change | | `run_worker_first: true` | the Worker runs for everything | every request is billed | The route-pattern form is usually right. It needs Wrangler 4.20.0 or later, and with an array the navigation header no longer decides anything: matched paths reach the Worker, and other misses get `index.html` without invoking code. ```json { "name": "spa-move", "main": "src/index.js", "compatibility_date": "2026-10-10", "assets": { "directory": "./dist", "binding": "ASSETS", "not_found_handling": "single-page-application", "run_worker_first": ["/auth/callback", "/api/*"] } } ``` ## Hardening the callback route - Validate `state` against the value stored before the redirect, and exchange `code` on the server side, never in the browser. - Set the session cookie with `HttpOnly`, `Secure` and `SameSite`, and redirect to `/` afterwards, so the code does not linger in the address bar or history. - Keep the provider's client secret in a Worker secret, not in a var or the assets directory. ## How to avoid the class of bug When moving from Pages, list every path that a browser can **navigate** to and that needs code: auth callbacks, file downloads generated on the fly, server-rendered pages, webhook landing pages opened by users. Put them in `run_worker_first`. Paths that are only ever fetched by your scripts need no entry, because non-navigation misses already reach the Worker. Keep the list next to the routes it serves and review it with them: a new server-rendered page or a second identity provider adds a path, and a stale list fails the same silent way, with the shell answering and no error anywhere in the logs. A smoke test that sends one navigation request to each listed path under `wrangler dev` and expects a non-HTML response is cheap insurance.
- Why does calling /auth/callback with curl reach the Worker when the browser redirect does not?The navigation shortcut keys on the `Sec-Fetch-Mode: navigate` header. Browsers add it when loading a page or following a redirect; `curl` and a page's `fetch()` do not. Without it, a miss takes the normal path and invokes the Worker. Add `-H "Sec-Fetch-Mode: navigate"` to reproduce what the browser sees.
- When is the assets_navigation_has_no_effect flag a better fix than run_worker_first patterns?When the Worker must see nearly every navigation that misses, for example because it renders HTML on the server for many routes that would be tedious to list. The cost is that every such navigation becomes a billed invocation. For a mostly client-rendered app with a few server routes, explicit patterns are cheaper and clearer.
- The OAuth callback fails because Workers cannot read query strings on navigations
- single-page-application mode never lets any request that misses reach the Worker script
- Setting html_handling to none makes navigations reach the Worker
- The fix is to add /auth/callback to _redirects with a 200 code
- The behaviour is a local-only quirk of wrangler dev that production does not share
Assumes a compatibility date from 2025-04-01, when assets_navigation_prefers_asset_serving became the default, and Wrangler 4.20.0 or later for run_worker_first route patterns.