Troubleshooting

Fix common build and runtime errors involving optional dependencies, AI Chat and MCP, docs 404s, i18n configuration, pnpm build approvals and commit history.
View source

Build fails with "已启用的功能缺少依赖"

AI Chat, component docs, Mermaid and a11y are off by default, and their dependencies are optional peer dependencies of the layer that are not installed automatically. When you turn one on, the layer checks its dependencies before the build starts and stops with an install command if any are missing. The message reads "enabled features are missing dependencies"; run the command it prints. See Feature Flags for each feature's packages:

FeaturePackages to install
AI Chatai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
Component docsnuxt-component-meta vue-component-meta prettier
Mermaidmermaid dompurify
a11y@nuxt/a11y

AI Chat turns on automatically when AI_API_KEY exists in the build environment, so if CI has that variable you need the AI Chat packages; set aiChat.enabled: false if you do not want it.

Build fails with "aiChat 依赖 MCP Server"

The message means "aiChat depends on the MCP Server; do not set movkNuxtDocs.mcp: false while aiChat is enabled". AI Chat searches the docs through the site's own MCP Server, so the two cannot be separated. Keep MCP, or turn AI Chat off as well:

nuxt.config.ts
export default defineNuxtConfig({
  aiChat: {
    enabled: false
  },
  movkNuxtDocs: {
    mcp: false
  }
})

Every docs page returns 404

This warning at build time means the layer found no docs directory:

terminal
[@movk/nuxt-docs] 未找到 content/docs 目录,文档页面固定位于 /docs 下,请将文档放入 content/docs/

Docs must live in content/docs/ and are always served under /docs; in multilingual sites other locales go in content/{code}/docs/. Move your docs there. Numeric prefixes in file names only control ordering and do not appear in URLs. See Project Structure.

Build fails after enabling multiple languages

When an entry in i18n.locales declares file, @nuxtjs/i18n looks for translation files in your site's own i18n/locales/ directory and fails when they are missing. Remove file and keep only code and name:

nuxt.config.ts
export default defineNuxtConfig({
  i18n: {
    defaultLocale: 'zh-CN',
    locales: [
      { code: 'zh-CN', name: '简体中文' },
      { code: 'en', name: 'English' }
    ]
  }
})

A locale has no effect

If the build log warns about a missing translation file (缺少翻译文件) or a missing content directory (缺少内容目录), that locale was skipped:

terminal
[movk-docs] 缺少内容目录 content/en/,已跳过 locale "en"

A non-default locale needs both a translation file shipped with the layer (currently zh-CN and en) and a content/{code}/ directory. See Internationalization.

Image processing fails after a pnpm install

pnpm does not run dependency install scripts by default, and sharp, used by @nuxt/image, has to be allowed explicitly. Declare it in pnpm-workspace.yaml at the project root:

pnpm-workspace.yaml
allowBuilds:
  sharp: true

You can also run pnpm approve-builds and pick it interactively. Run pnpm install again afterwards. The official templates already include this setting.

Since pnpm 11, build approvals use allowBuilds; older settings such as onlyBuiltDependencies were removed. See the pnpm docs.

Missing peer dependency tailwindcss

nuxt, @nuxt/content and tailwindcss are required peer dependencies and must be installed in your project:

pnpm add nuxt @nuxt/content tailwindcss

Commit history and last updated time are missing

CommitChangelog and PageLastCommit request GitHub data from the browser. Check, in order:

  1. Whether NUXT_GITHUB_TOKEN is set in the runtime environment. Without a token the endpoints return empty results;
  2. Whether github.owner, github.name and github.branch in app.config match the repository. When they are unset the layer infers them from Git, and there is no data if that fails;
  3. Whether github.rootDir points to the docs directory when the docs are not at the repository root;
  4. Whether the site is deployed as static files. A static site has no /api/github/* endpoints; see Deployment.

AI Chat does not appear

Whether AI Chat is bundled is decided at build time: the build environment needs AI_API_KEY, or aiChat.enabled: true in nuxt.config.ts. Setting the variable only at runtime does not add AI Chat to an existing build; rebuild after configuring it. See AI Chat.

Google Fonts requests fail

terminal
Could not fetch from https://fonts.google.com/metadata/fonts. Will retry in 1000ms. 3 retries left.

The layer sets ui.fonts: false and self-hosts Inter, Fraunces and JetBrains Mono, so it never requests Google Fonts. This warning means @nuxt/fonts was turned back on in your project; turn it off again:

nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    fonts: false
  }
})

To add Chinese fonts, see Theme & Fonts.

Copyright © 2024 - 2026