[clerk-nuxt] Auto-registered Nitro server middleware breaks h3 auto-imports — ReferenceError: H3Error is not defined

[ericcorriel]

Preliminary Checks

• I have reviewed the documentation: https://clerk.com/docs

• I have searched for existing issues: https://github.com/clerk/javascript/issues

• I have not already reached out to Clerk support via email or Discord (if you have, no need to open an issue here)

• This issue is not a question, general help request, or anything other than a bug report directly related to Clerk. Please ask questions in our Discord community: https://clerk.com/discord.

Reproduction

https://github.com/ericcorriel/clerk-nuxt-bug

Publishable key

pk_test_aW5maW5pdGUtZmxlYS04Ni5jbGVyay5hY2NvdW50cy5kZXYk

Description

Repro repo

https://github.com/ericorriel/clerk-nuxt-bug

Standalone minimal Nuxt 4.4.4 + @clerk/nuxt 2.2.9 project. Clone, yarn install, copy .env.example to .env and paste Clerk dev keys, yarn dev, visit http://localhost:3000/ — the bug fires immediately on first request.

The repo also includes the workaround we shipped (commented-out config block + a hand-rolled middleware in server/middleware/clerk.ts). Uncomment the workaround block in nuxt.config.ts, rm -rf .nuxt, restart, and the page renders cleanly.

Summary

When @clerk/nuxt is added to a Nuxt 4 app's modules array with default settings, every SSR-rendered page throws ReferenceError: H3Error is not defined at module-load time. The Nitro dev bundle's auto-imports virtual module references h3 helpers (H3Error, H3Event, appendCorsHeaders, and others) without emitting the corresponding import statements at the top of the bundle.

Disabling Clerk's auto-registered server middleware via clerk: { skipServerMiddleware: true } is a workaround, but importing clerkMiddleware from @clerk/nuxt/server to register the middleware manually re-triggers the bug. Only avoiding @clerk/nuxt/server entirely (and using @clerk/backend directly) sidesteps it.

Reproduced on

Package	Versions tested
nuxt	4.3.1, 4.4.4 (latest stable)
@clerk/nuxt	2.2.8, 2.2.9 (latest stable)
@nuxt/nitro-server	4.3.1, 4.4.4
unimport	5.6.0, 5.7.0, 6.2.0 (latest)
h3	1.15.6

The bug is consistent across all combinations above.

Stack trace

ReferenceError: H3Error is not defined
    at /path/to/.nuxt/dev/index.mjs:7673:12
    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:665:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:117:5)

The line number varies slightly with bundle size; the symbol may also be H3Event, appendCorsHeaders, setHeaders, etc. — anything in @nuxt/nitro-server's h3 auto-imports preset that user code doesn't already import explicitly.

Diagnosis

Inspecting the generated .nuxt/dev/index.mjs, the bundle contains an auto-imports virtual module:

const _virtual__imports = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
  __proto__: null,
  // ... user-defined symbols ...
  H3Error: H3Error,        // <-- ReferenceError fires here
  H3Event: H3Event,
  appendCorsHeaders: appendCorsHeaders,
  // ... more h3 symbols ...
}));

But the top-of-file h3 import only includes the subset of h3 helpers that user code references explicitly:

import { defineEventHandler, createError, eventHandler, /* ... ~30 more ... */ } from 'h3';
// H3Error, H3Event, appendCorsHeaders NOT in this list

So H3Error/H3Event/etc. are referenced as values in the virtual imports object but were never imported into the bundle's scope.

@nuxt/nitro-server registers these as auto-imports via:

// node_modules/@nuxt/nitro-server/dist/index.mjs (at line 229 in 4.4.4)
presets: [{
  from: 'h3',
  imports: ['H3Event', 'H3Error']
}, ...]

This preset works correctly when @clerk/nuxt is not in the modules array — the bundler emits the corresponding import statements and everything is fine. Adding @clerk/nuxt is the trigger.

What we tried (none of these worked)

1. Pinning unimport to 5.6.0, 5.7.0, and ^6.2.0 via yarn resolutions. Same error every time.
2. Explicit user import: adding import { H3Error, H3Event } from 'h3' to a server plugin file. The bundler tree-shakes the plugin away or unimport strips the import as already-auto-registered. Either way the import statement never appears in the final bundle.
3. Explicit nitro.imports.imports config with [{ name: 'H3Error', from: 'h3' }, ...]. No effect — the bundle still misses the import.
4. Stripping the h3 value-preset via a nitro:config hook in nuxt.config.ts. This made H3Error materialize correctly, but the next preset entry (appendCorsHeaders) failed identically — the bug is preset-wide, not specific to particular symbols.
5. Upgrading Nuxt from 4.3.1 to 4.4.4. Bug persists.
6. Manual middleware registration in server/middleware/clerk.ts with import { clerkMiddleware } from '@clerk/nuxt/server'. This re-triggers the bug — importing anything from @clerk/nuxt/server is enough; the auto-registration isn't the only path that breaks the bundle.

Workaround that worked

1. Set clerk: { skipServerMiddleware: true } in nuxt.config.ts.
2. Hand-roll a Nitro middleware using @clerk/backend directly:

// server/middleware/clerk.ts
import { createClerkClient } from '@clerk/backend'

let clerkSingleton: ReturnType<typeof createClerkClient> | null = null

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event)
  const secretKey = config.clerk?.secretKey
  if (!secretKey) {
    event.context.auth = () => ({ isAuthenticated: false, userId: null, sessionId: null, sessionClaims: null })
    return
  }
  if (!clerkSingleton) {
    clerkSingleton = createClerkClient({
      secretKey,
      publishableKey: config.public?.clerk?.publishableKey
    })
  }
  try {
    const requestState = await clerkSingleton.authenticateRequest(toWebRequest(event), { acceptsToken: 'any' })
    event.context.auth = () => requestState.toAuth()
    if (requestState.headers) {
      requestState.headers.forEach((value, key) => setResponseHeader(event, key, value))
    }
  } catch {
    event.context.auth = () => ({ isAuthenticated: false, userId: null, sessionId: null, sessionClaims: null })
  }
})

This is functionally identical to the clerkMiddleware() export from @clerk/nuxt/server for our use case (we don't use keyless mode or the handshake redirect flow). Importantly, it imports only from @clerk/backend (a transitive dep we already pull in via @clerk/nuxt) and from h3 — no @clerk/nuxt/server path is involved at the bundle level.

With this in place, the bundler emits import { ... } from 'h3' correctly with all the symbols the auto-imports virtual module references, the bundle loads, and event.context.auth() works exactly as before.

Hypothesis

Something in @clerk/nuxt's server-runtime entry or its internal exports interacts with unimport's scanner in a way that registers h3 auto-imports as "tracked" but somehow short-circuits the bundler's import-injection step. The corruption manifests in any code path that pulls @clerk/nuxt/server into the bundle — auto-registered middleware, manually-registered middleware via clerkMiddleware() import, possibly other entry points.

I haven't isolated the exact mechanism, but the workaround above sidesteps it cleanly by using @clerk/backend directly. Happy to add more diagnostics if helpful.

Environment

• macOS 26 (Apple Silicon)
• Node.js (latest LTS)
• yarn 1.22.22
• Nuxt 4.4.4 with Vite/Nitro defaults
• Other Nuxt modules in our production project: shadcn-nuxt, @nuxtjs/tailwindcss, @nuxtjs/color-mode. Removing these does not affect the bug — the standalone repro repo above includes none of them.

Impact

For any Nuxt 4 app adopting @clerk/nuxt server-side, this is a hard blocker on default usage — every SSR page crashes. The workaround restores functionality but adds maintenance burden (the project has to track when the upstream fix lands and remove the workaround). It also subtly changes behavior on edge cases not covered by the hand-rolled middleware (keyless mode, handshake redirects).

A Nuxt-4 + Clerk migration was the trigger that surfaced this for us; we're shipping the workaround in production while we wait for an upstream fix. Happy to test patches or canaries against the repro repo.

Environment

- macOS 26 (Apple Silicon)
- Node.js (latest LTS)
- yarn 1.22.22
- Nuxt 4.4.4 with Vite/Nitro defaults
- Other Nuxt modules in our production project: `shadcn-nuxt`, `@nuxtjs/tailwindcss`, `@nuxtjs/color-mode`. Removing these does not affect the bug — the standalone repro repo above includes none of them.

[wobsoriano]

Hello, thanks for reporting! I only see a README file in the repro. I have a PR here that should resolve it #8439

You can try it with this snapshot version:

npm i @clerk/nuxt@2.3.1-snapshot.v20260501171802 --save-exact

Let me know if that works

[ericcorriel]

Thanks for the quick response! Apologies for the empty repo–I've fixed that now. Unfortunately this fix didn't work.

Here's where I'm at with Claude on this:

Tested @clerk/nuxt@2.3.1-snapshot.v20260501171802 with the workaround fully removed (clerk: { skipServerMiddleware: true } deleted from nuxt.config.ts, hand-rolled server/middleware/clerk.ts deleted).

Same failure. ReferenceError: H3Error is not defined on any SSR-rendered protected page (/dashboard, /login, etc.). The compiled dev bundle at .nuxt/dev/index.mjs:7835 still has the offending pattern unchanged:

// inside an exported auto-imports object
H3Error: H3Error,
H3Event: H3Event,

…with no import { H3Error, H3Event } from 'h3' at the top of the file. Throws at module-load time the moment an SSR route runs.

Possibly useful — dev vs. prod diverge:

Running yarn build (production) with the snapshot + workaround removed produces a Nitro bundle where H3Error is properly defined as a class in chunks/nitro/nitro.mjs and the previously-broken chunks/virtual/_virtual_imports.mjs chunk is no longer emitted at all. So the snapshot may have addressed the production codepath but not the dev-mode (nuxt dev) one — which is where the original repro lives.

I haven't actually run the prod build to confirm it serves cleanly end-to-end, just confirmed the bundle output looks healthy.

Environment:

• Nuxt 4.4.4 / Nitro 2.13.4 / Vite 7.3.2
• macOS, Node 22.x
• @clerk/nuxt@2.3.1-snapshot.v20260501171802 (exact)

Screenshot attached

[wobsoriano]

Thanks for the updated repo and the detailed breakdown.

I cloned it and tested locally with npm, pnpm, and yarn, running nuxt dev, and wasn't able to reproduce the error on either @clerk/nuxt@2.2.10 (the version you originally reported) or the snapshot @clerk/nuxt@2.3.1-snapshot.v20260501171802. Both ran without throwing ReferenceError: H3Error is not defined in dev mode.

A couple of things worth checking on your end:

• Make sure .nuxt/ is fully cleared before starting (rm -rf .nuxt && nuxt dev) - stale dev bundles can persist the old generated output even after a package upgrade.
• Confirm the snapshot is actually being resolved. Running nuxt info in your project will show the exact version of @clerk/nuxt Nuxt picked up.

If neither of those helps, could you share the output of nuxt info? That would help narrow down whether this is environment-specific.

[ericcorriel]

@wobsoriano so sorry, you're correct; the issue is on my end. Apologies for the runaround!

[wobsoriano]

All good! thanks for confirming 👊🏼

[ericcorriel]

For anyone landing here the trigger in this case was await import('#imports') somewhere in the code (used to dynamically reach useRuntimeConfig from a shared chunk). That dynamic import forces Nuxt's bundler to materialise a top-level _virtual__imports = Object.freeze({...}) block listing every auto-importable symbol in the project — including 4 specific h3 ones (H3Error, H3Event, appendCorsHeaders, appendCorsPreflightHeaders) that unimport adds to the manifest but never injects an import { ... } from 'h3' statement for. They end up referenced unbound in the freeze block and throw at module-load time.

@clerk/nuxt doesn't cause the bug — it just makes the bundle large enough that the asymmetry becomes visible.

How to find it in your own code

grep -rn "import(['\"]#imports['\"]" .

If you have any matches, that's almost certainly your trigger.

How to fix it

Replace the await import('#imports') with a direct import from the source module. For useRuntimeConfig specifically:

// ❌ before — triggers the asymmetry
const mod = await import('#imports' as any)
const runtime = mod.useRuntimeConfig?.(event)

// ✅ after — bypasses the auto-imports virtual entirely
const { useRuntimeConfig } = await import('nitropack/runtime')
const runtime = useRuntimeConfig(event)

Once that's gone, _virtual__imports is no longer generated, the four h3 symbols vanish from the bundle.