SSR: `_api.setFetch($fetch.native)` disables icon loading entirely — `useRequestFetch()` returns Nitro's `event.$fetch`, which has no `.native`

[afuno]

Versions

@nuxt/icon	2.4.0, 2.4.1 (2.3.1 unaffected)
nuxt	4.5.1
nitropack	2.13.4
@iconify/vue	5.0.1
ofetch	1.5.1

Symptom

Every <Icon> fails to render server-side. The SSR HTML contains <span class="iconify i-…"> placeholders with no data:image/svg+xml mask, and the server logs one [Icon] failed to load icon <name> per icon per render. The browser then resolves them after hydration, so the icons appear — blank until then.

No network request is made at any point. Not a failed request, not a 404 — none at all. The request is abandoned before a URL is constructed, which is what makes this hard to recognise: the usual diagnostics (check the API endpoint, check connectivity, check CSP) all come back clean.

Root cause

dist/runtime/plugin.js changed in 2.4.0. Two lines, against 2.3.1:

-import { defineNuxtPlugin, useAppConfig, useRuntimeConfig } from "#imports";
+import { defineNuxtPlugin, useAppConfig, useRequestFetch, useRuntimeConfig } from "#imports";
 ...
-    _api.setFetch($fetch.native);
+    const $fetch = useRequestFetch();
+    _api.setFetch($fetch.native);

In 2.3.1 $fetch is Nuxt's auto-imported ofetch instance on both server and client. In 2.4.x the local binding shadows it, and on the server it is a different object:

1. useRequestFetch() returns useRequestEvent()?.$fetch || $fetch — nuxt/dist/app/composables/ssr.js:37-40. During SSR the event exists, so the first branch wins.
2. Nitro assigns that property as a plain arrow function, not an ofetch instance — nitropack/dist/runtime/internal/app.mjs:62-63:

   event.$fetch = (req, init) => fetchWithEvent(event, req, init, { fetch: $fetch });

   It carries no .native, so $fetch.native is undefined. (The ofetch instance with .native is the one assigned to globalThis.$fetch at app.mjs:110-115 — the one 2.3.1 used.)
3. _api.setFetch(undefined) assigns fetchModule = undefined — @iconify/vue/dist/iconify.mjs:669-670.
4. send() bails at the top — iconify.mjs:746-750:

   const send = (host, params, callback) => {
     if (!fetchModule) {
       callback("abort", 424);
       return;
     }

   fetchModule(host + path) is at :770, so the abort happens before any URL is built.

Worth noting that step 3 does not merely fail to supply a fetch — it destroys a working one. @iconify/vue initialises fetchModule = detectFetch() (iconify.mjs:655-665), which picks up the global fetch and would have worked. The plugin overwrites it with undefined.

Why the client is unaffected

useRequestFetch() returns the global ofetch instance in the browser (ssr.js:38, if (import.meta.client) return $fetch), and that does carry .native. Only the server branch is broken, which is why the icons appear after hydration and the bug reads as a rendering delay rather than a failure.

Reproduction

1. Nuxt 4.5 app, SSR on, @nuxt/icon 2.4.1, no icon config.
2. One <Icon name="fa6-solid:moon" /> on a page.
3. nuxt build && node .output/server/index.mjs, request the page.

Expected: the server-rendered HTML contains a data:image/svg+xml mask for the icon.
Actual: it contains an empty <span class="iconify i-fa6-solid:moon">, the server logs [Icon] failed to load icon fa6-solid:moon, and no outbound request is made.

Downgrading to 2.3.1 with no other change fixes it.

The fix is not to restore .native

ofetch defines it as a raw passthrough — ofetch/dist/shared/ofetch.CWycOUEr.mjs:336:

$fetch.native = (...args) => fetch(...args);

It discards ofetch's decoration and any request context. So #514 ("fix: avoid relying on global fetch") could not have delivered request-scoped fetching even if event.$fetch had carried .native: taking .native off any instance strips exactly the scoping the change set out to preserve, in 2.3.1 no less than in 2.4.x.

Making event.$fetch expose .native would restore the previous behaviour but not achieve the stated goal. If request-scoped fetching is wanted, _api.setFetch needs a function that actually routes through the event — for example wrapping useRequestFetch() itself rather than reaching for a property that is defined to bypass it.

Workaround

Bundle the icons so the fetch path is never reached:

export default defineNuxtConfig({
  icon: {
    clientBundle: {
      icons: ['fa6-solid:moon', /* … */],
      scan: true,
    },
  },
})

loadIcon() calls initClientBundle(_addIcon) and returns early if _getIcon(name) resolves, before _loadIcon is reached — dist/runtime/components/shared.js:6-13. This runs on the server as well as the client, so it is independent of serverBundle mode. It also removes the runtime dependency on the Iconify CDN, which is worth having regardless of this bug.

[coderabbitai]

🔗 Related PRs

#493 - fix(server): use ufo for query parsing to fix h3 v2 compatibility [closed]
#504 - fix: don't hard-fail on unresolvable hook-contributed client bundle icons [merged]
#506 - feat: standalone Vite plugin and reusable utils for client icon bundling [merged]
#514 - fix: avoid relying on global fetch [open]
#516 - fix: support Nitro 3 runtime imports [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[NtchPlayer]

Yes, I get the same error.
I use @iconify-json/fa7-brands, @iconify-json/fa7-regular, @iconify-json/fa7-solid.

And a lot of icon that I use don't load :

WARN [Icon] failed to load icon fa7-solid:compact-disc.

I don't have the problème on v2.3.1.

My config :

|                      |                                                                                                                                                                                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Node.js version**  | `v24.18.0`                                                                                                                                                                                                                                                                                    |
| **nuxt/cli version** | `3.37.0`                                                                                                                                                                                                                                                                                      |
| **Package manager**  | `npm@12.0.1`                                                                                                                                                                                                                                                                                  |
| **Nuxt version**     | `4.5.1`                                                                                                                                                                                                                                                                                       |
| **Nitro version**    | `2.13.4`                                                                                                                                                                                                                                                                                      |
| **Builder**          | `vite@8.1.5`                                                                                                                                                                                                                                                                                  |
| **Config**           | `alias`, `app`, `compatibilityDate`, `css`, `devtools`, `eslint`, `experimental`, `googleFonts`, `i18n`, `icon`, `imports`, `modules`, `nitro`, `pwa`, `robots`, `runtimeConfig`, `site`, `sitemap`, `vWave`, `vite`, `vue`                                                                   |
| **Modules**          | `@nuxt/eslint@1.16.0`, `@nuxtjs/i18n@10.5.0`, `@vite-pwa/nuxt@1.1.1`, `@nuxtjs/sitemap@8.3.0`, `@nuxtjs/robots@6.1.3`, `@pinia/nuxt@1.0.1`, `@nuxtjs/color-mode@4.0.1`, `v-wave/nuxt@3.1.1`, `@nuxtjs/google-fonts@3.2.0`, `@nuxt/icon@2.4.1`, `nuxt-vitalizer@2.0.0`, `@regle/nuxt@1.28.5`   |

[rastuhacode]

I also have the same issue, pinning 2.3.1fixed the warnings.

[nikulsons]

Confirming this on 2.5.0, with a bisect against 2.2.3

We hit this on a Nuxt 4.5.2 app (@nuxt/icon 2.5.0, icons served from locally installed @iconify-json/lucide + @iconify-json/simple-icons, plus a client bundle). Every SSR request logs one [Icon] failed to load icon `<name>` warning per client-resolved icon on the page.

To isolate the module version we rendered the same page on the same dev server under both versions and diffed:

	@nuxt/icon 2.2.3	@nuxt/icon 2.5.0
SSR HTML (same page)	16 inlined <svg>, 28 client-only iconify spans	byte-identical — same 16 / 28
Server log per SSR request	silent	one failed to load icon warning per client-only icon

So for our setup the regression is observable purely as per-request log spam — the SSR output is unchanged because the affected icons were already client-resolved — but it confirms the mechanism described here: the loads abort server-side before any request is attempted (fetchModule ends up undefined, so Iconify's send() bails with 424), and the previously working detectFetch fallback is what 2.2.3 was silently benefiting from.

Two data points that may help scope the fix:

• The issue is filed against 2.4.0/2.4.1 — 2.5.0 is still affected.
• The abort produces no network traffic at all, so anyone grepping access logs for failed icon fetches will find nothing; the only signal is the runtime warning.

We've pinned 2.2.3 for now. The prioritized fetch selection in #527 looks like the right shape — happy to test a pre-release against this setup if useful.

[rastuhacode]

@nikulsons additional test would be great!

If you want and have a free time, you can test modified version with:

npm i https://pkg.pr.new/@nuxt/icon@527

you can find actual command (if any additional commits would be added) in PR pkg-pr-new comment

[nikulsons]

Tested npm i https://pkg.pr.new/@nuxt/icon@527 against the same Nuxt 4.5.2 setup as my comment above:

	2.2.3 (baseline)	2.5.0 (broken)	PR #527 build
SSR HTML (same page)	16 inlined <svg> / 28 client spans	byte-identical	byte-identical
Server log per SSR request	silent	one warning per client-only icon	silent

The prioritised fetch selection resolves it for our setup with no warnings, no rendering change. LGTM from here. Happy to re-test if the PR picks up more commits.