Dev server hydration errors when using bun

[notnotjake]

Describe the bug

When running the dev server with bun (bun --bun vite dev) hydration errors can occur. In practice these are intermittent but can be reproduced by anything that calls sync.create() (see reproduction steps below).

As best as I understand it, create_manifest_data assigns numeric node indices based on the order fs.readdirSync() returns directory entries. This ordering is not guaranteed by POSIX and differs between runtimes: node returns entries alphabetically, while bun returns them in filesystem/creation order.

This means the same project produces different client/app.js manifests depending on which runtime calls sync.create(). When the dev server's in-memory SSR manifest uses one ordering but the on-disk client manifest uses another, the SSR-emitted node_ids point to the wrong components, causing hydration failures and wrong page content.

This can happen if while you are running the dev server, you run a different command with node or your IDE or AI agent run something with node that triggers the sync.

Root cause (?)

packages/kit/src/core/sync/create_manifest_data/index.js line 217:

const files = fs.readdirSync(dir).map((name) => ({

Node indices are assigned from this traversal order (line 416) before sort_routes() is called (line 464).

Reproduction

1. Create a SvelteKit project with multiple route groups - e.g. (app), (marketing)
2. Start the dev server with bun --bun vite dev
3. In a separate terminal, run sync.create() under Node:

   node --input-type=module -e '
   import { load_config } from "./node_modules/@sveltejs/kit/src/core/config/index.js";
   import * as sync from "./node_modules/@sveltejs/kit/src/core/sync/sync.js";
   const config = await load_config();
   sync.all(config, "development");
   '

4. Navigate to any route — wrong page content loads, console shows HierarchyRequestError: The operation would yield an incorrect node tree

Logs

System Info

System:
    OS: macOS 26.3
    CPU: (10) arm64 Apple M1 Max
    Memory: 179.69 MB / 32.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 25.6.0 - /opt/homebrew/bin/node
    npm: 11.8.0 - /opt/homebrew/bin/npm
    bun: 1.3.9 - /Users/jake/.bun/bin/bun
  Browsers:
    Chrome: 144.0.7559.134
    Safari: 26.3
  npmPackages:
    @sveltejs/kit: ^2.50.2 => 2.50.2
    @sveltejs/vite-plugin-svelte: ^6.2.4 => 6.2.4
    svelte: ^5.50.1 => 5.50.1
    vite: ^7.3.1 => 7.3.1

Severity

annoyance

Additional Information

No response

[notnotjake]

I created a fork and made the following change which fixed the issue:

main...notnotjake:sveltekit:fix/sort-route-manifest-traversal

packages/kit/src/core/sync/create_manifest_data/index.js - line 217

- const files = fs.readdirSync(dir).map((name) => ({
+ const files = fs.readdirSync(dir).sort().map((name) => ({

It doesn't seem to have impacted anything else but I don't understand the code well enough to say whether this is a clean fix or if it has side effects.

[jose-manuel-silva]

Hit this bug independently - adding concrete data.

Setup: macOS, Bun 1.3.10, Node 25.6.1, SvelteKit 2.53.4

readdirSync ordering difference confirmed:

Node: +layout.server.ts, +layout.svelte, [brand], admin, diagnostics, family-targets, ...
Bun:  family-targets, [brand], processes, lost-sales, admin, +layout.server.ts, ...

Resulting node index mismatch (ran create_manifest_data() under both runtimes, same project):

Route	Node.js	Bun
/(app)/family-targets	Node 16	Node 8
/(app)/[brand]/allocation-history	Node 8	Node 12

Trigger in my case: bun check runs svelte-kit sync which has #!/usr/bin/env node shebang, so it runs under Node. Meanwhile the dev server runs under Bun. Even though svelte-kit sync only calls all_types() (not create()), anything that calls sync.create() or sync.all() under a different runtime will desync the client manifest files.

Symptom: Server SSR renders the correct page but embeds wrong node_ids. Client loads the wrong component from disk and hydrates over the correct SSR content.

[notnotjake]

bumping this. would love if this could get addressed

[hjaber]

Adding another data point from a real app, but I can't yet pin it down enough to provide a minimal repro or say confidently that it is the same root cause.

Setup:

• macOS dev machine
• dev command: bunx --bun vite dev --host --open
• @sveltejs/kit@2.61.1
• svelte@5.56.1
• @sveltejs/vite-plugin-svelte@7.1.2
• vite@8.0.16
• kit.experimental.remoteFunctions: true
• kit.experimental.handleRenderingErrors: true
• compilerOptions.experimental.async: true

Trigger in my case:

• This shows up around HMR, usually after fairly large route/component code changes.
• I have not been able to intentionally repeat it with a small set of steps.
• I have not confirmed that a separate Node-run sync.create()/sync.all() is involved. The obvious thing in my case is just the Bun dev server plus HMR/code edits.

Symptoms:

• The dev server logs do not report a server error and appear to think HMR worked.
• The browser can end up showing what looks like a 500/error state, but I don't see a matching 500 in the Network tab.
• Restarting the dev server fixes it immediately.
• The browser console errors vary between attempts. Examples I've seen:

The next HMR update will cause the page to reload
HierarchyRequestError: Failed to execute 'appendChild' on 'Node': This node type does not support this method.
[svelte] hydration_mismatch Hydration failed because the initial UI does not match what was rendered on the server
Failed to hydrate: TypeError: Cannot read properties of null (reading 'nodeType')
TypeError: Cannot read properties of undefined (reading 'length')

The stack often goes through Svelte hydration/runtime functions like skip_nodes, child, Boundary, generated root.svelte, and route +layout.svelte/+page.svelte frames.

I'm mostly adding this because the symptoms overlap with this issue: Bun dev server, intermittent hydration/HMR corruption, no useful server logs, and restart clears it. But I can't yet say whether the underlying mechanism is the manifest ordering mismatch described above or a separate HMR + experimental async/remote-functions path.