---
title: "Troubleshooting"
description: "Fix common build and runtime errors involving optional dependencies, AI Chat and MCP, docs 404s, i18n configuration, pnpm build approvals and commit history."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/guide/troubleshooting"
---
# Troubleshooting

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

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

```text [terminal]
[@movk/nuxt-docs] 已启用的功能缺少依赖：
  - mermaid: mermaid, dompurify
请安装后重试：pnpm add mermaid dompurify
```

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](https://docs.mhaibaraai.cn/en/docs/guide/features) for each feature's packages:

| Feature | Packages to install |
| --- | --- |
| AI Chat | `ai` `@ai-sdk/openai` `@ai-sdk/vue` `@comark/vue` `@shikijs/engine-javascript` `@shikijs/langs` `@shikijs/themes` |
| Component docs | `nuxt-component-meta` `vue-component-meta` `prettier` |
| Mermaid | `mermaid` `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"

```text [terminal]
[@movk/nuxt-docs] aiChat 依赖 MCP Server，请勿在启用 aiChat 时设置 movkNuxtDocs.mcp: false
```

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:

```ts [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:

```text [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](https://docs.mhaibaraai.cn/en/docs/getting-started/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`:

```ts [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:

```text [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](https://docs.mhaibaraai.cn/en/docs/guide/i18n#when-a-locale-is-valid).

## 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:

```yaml [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.

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

## Missing peer dependency tailwindcss

```text [terminal]
WARN  Issues with peer dependencies found
└─┬ @movk/nuxt-docs
  └── ✕ missing peer tailwindcss@4.x
```

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

```bash [pnpm]
pnpm add nuxt @nuxt/content tailwindcss
```

```bash [npm]
npm install nuxt @nuxt/content tailwindcss
```

```bash [yarn]
yarn add nuxt @nuxt/content tailwindcss
```

```bash [bun]
bun add nuxt @nuxt/content tailwindcss
```

## Commit history and last updated time are missing

[`CommitChangelog`](https://docs.mhaibaraai.cn/en/docs/components/commit-changelog) and [`PageLastCommit`](https://docs.mhaibaraai.cn/en/docs/components/page-last-commit) 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](https://docs.mhaibaraai.cn/en/docs/guide/deployment#static-generation).

## 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](https://docs.mhaibaraai.cn/en/docs/ai/ai-chat).

## Google Fonts requests fail

```text [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:

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

To add Chinese fonts, see [Theme & Fonts](https://docs.mhaibaraai.cn/en/docs/guide/theme).


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
