---
title: "Next.js"
description: "Fix Next.js configuration errors, missing translations, language switching, and hydration problems."
canonical_url: "https://docs.linguana.dev/docs/troubleshooting/nextjs"
markdown_url: "https://docs.linguana.dev/docs/troubleshooting/nextjs.md"
x_farming_labs_generated_preamble: true
---

# Next.js
URL: /docs/troubleshooting/nextjs
LLM index: /llms.txt
Description: Fix Next.js configuration errors, missing translations, language switching, and hydration problems.

# Troubleshoot Next.js

Most problems show up as a configuration error when Next.js loads `next.config.*`, or as a `[linguana]` warning in the server log. Keep the warning text; it never contains your token.

## Configuration errors

### `Linguana requires Next.js 16.`

`@linguanahq/next` supports Next.js 16 only. Upgrade `next`, `react`, and `react-dom` together to Next.js 16 and React 19.

### `Linguana cookie-based translation requires a Next.js server; remove output: 'export'.`

Static export cannot read the request's language cookie or headers. Remove `output: "export"` and deploy with a Node.js server.

### `Linguana does not yet support cacheComponents; disable it for cookie-based translation.`

Remove `cacheComponents: true` from your Next.js configuration. Keep request-dependent translated content out of `"use cache"` scopes.

### `Linguana upload requires a build token.`

`upload` is `true` but `token` is empty. Set `LINGUANA_PROJECT_TOKEN` in the build environment, or set `LINGUANA_UPLOAD=false` for builds that should not upload, such as pull-request previews.

### `Linguana translation requires upload, a token, and development publication.`

Build translation runs only for development uploads. Use `upload: true`, a development token, `environment: "development"`, and `translation: { enabled: true, publish: "development", maxChargeMicros }`. Publish production catalogs from the dashboard instead.

### `Conflicting withLinguana configurations.`

The wrapper was applied twice with different options, for example in a shared base config and again in the app. Apply `withLinguana` once.

### `Linguana requires projectId.` or `Invalid Linguana cookieName.`

Set a non-empty `projectId`, and use only letters, digits, `_`, and `-` in `runtime.cookieName`. If `projectId` comes from an environment variable, check that Next.js loaded the file that defines it.

## Extraction

### The manifest is missing or empty

The manifest is written by `next build`, not `next dev`. Check that `.linguana/manifest.json` exists after a successful build. If you set `include`, make sure the patterns match your `app/` and component directories. Source outside the application root needs explicit `include` patterns, or a `root` option pointing at the app.

### Text from tests, stories, or config files is missing

Tests, specs, declarations, and `*.config.*` files are excluded by default. Move product copy into application components.

## Runtime

### `Next.js translations require LinguanaProvider in the root layout.`

A Client Component called `useTranslation()` outside the provider. Render `LinguanaProvider` from `@linguanahq/next/server` around `children` in `app/layout.tsx`.

### `server-only` import error in a Client Component

`@linguanahq/next/server` can only be imported in server code. In Client Components, import `useTranslation` and `LanguageSelector` from `@linguanahq/next/client`, and `T` from `@linguanahq/next`.

### The page stays in the source language

Look for these server warnings:

| Warning | What to check |
| --- | --- |
| `Catalog unavailable; rendered source fallback.` | The language is published to the configured environment, `catalogEndpoint` is reachable from the server, and `publishableKey` is set |
| `Catalog scope or integrity verification failed; rendered source fallback.` | The catalog's project, environment, and source language match `withLinguana`. Do not edit catalog files by hand |
| `Language configuration unavailable; using embedded/source locales.` | `configEndpoint` or `catalogEndpoint` and `publishableKey`, or set `runtime.availableLocales` |
| `missing-translation` | The string is new or not yet in the published catalog. Translate, review, and publish it |

Runtime values are read when Next.js loads its configuration. Restart `next dev`, or rebuild for production, after changing them.

### The language selector does not switch

The target language must be in `availableLocales`, and its catalog must load within five seconds and pass verification. When it cannot, the current language stays and `useTranslation().diagnostics` contains `Language change failed; kept the previous language.` See [Language loading](/docs/troubleshooting/catalog-runtime).

### Hydration mismatch

Render all translated content under `LinguanaProvider`, and do not resolve the language again in Client Components, for example from `navigator.language`. The provider passes the server's language and catalogs to the client unchanged.

## Upload

Upload errors after `next build` behave as for the Vite plugin. See [Upload and authentication](/docs/troubleshooting/upload-and-auth). An upload or translation that completed is kept even if a later build stage, such as type checking, fails.

## Next

Review the [Next.js API](/docs/reference/next) for every option and default.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).