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:

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.

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. 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 for every option and default.