Hi @gentle echo. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
#Nuxt useHead TypeError
rugged torrentBOT
I'm happy to help with your Nuxt useHead TypeError issue!
Based on the knowledge sources, there have been several issues and changes related to the useHead composable in Nuxt, especially around recent updates and the migration to Unhead v2. Here are some key points that might help you troubleshoot:
-
Import Source Matters: In Nuxt 3, useHead is auto-imported and powered by Unhead. If you are importing useHead directly from @vueuse/head or @unhead/vue in your code or tests, this can cause issues, especially outside of Vue context (like in plugins or middleware). You should use the Nuxt auto-imported version or import from #app/composables/head if auto-imports are disabled. Importing from @unhead/vue directly can lead to errors such as "useHead() was called without provide context" outside of setup() functions. This is a breaking change with Unhead v2 and Nuxt v3+ updates feat(nuxt): upgrade Unhead v2 major.
-
Type Changes and Compatibility: With the upgrade to Unhead v2, the types for useHead have changed. In Nuxt v3, useHead can return void if no instance is available, but in Nuxt v4, it will throw an error if the context is missing. This means you need to ensure you are calling useHead in the correct context (inside setup or a component) feat(nuxt): upgrade Unhead v2 major.
-
Reactivity and Dynamic Data: useHead supports reactive, ref, and computed values. If you are trying to update meta tags dynamically (e.g., after fetching data), make sure you are passing a computed or reactive object to useHead useHead composable docs.
- Recent Regressions and Fixes: There have been regressions related to head reactivity and context, but these have been addressed in recent Nuxt and Unhead updates. If you are on an older version, try upgrading Nuxt and related packages and deduping dependencies (e.g., npx nuxt@latest upgrade --dedupe) Github Issue: Manually typing App Config doesn't work.
What to do:
- Double-check your import source for useHead.
- Ensure you are using the latest Nuxt and Unhead versions.
- Make sure useHead is called inside a setup function or component context.
- If you are using dynamic data, wrap your meta object in computed or ref.
- If you are running into issues in tests, use mockNuxtImport from nuxt-vitest/utils instead of mocking @unhead/vue directly Stack Overflow: Vitest - How do I assert that a flat function was called within a composable?.