Developer Docs Next.XP 5.x Troubleshooting

Troubleshooting

Start with the request path that is failing: direct Next.js rendering, Next.js-to-Guillotine fetching, or Content Studio-to-Next.js preview. The distinction usually identifies the responsible configuration.

Common symptoms

Symptom Checks

Symptom	Checks
Adapter reports a missing environment variable	Define `ENONIC_API`, `ENONIC_APP_NAME`, and `ENONIC_MAPPINGS` before the Next.js process starts. Rebuild when changing browser-visible variables.
Content returns 404	Check the locale mapping, XP project, site path, publication state, and requested site-relative path. Direct requests read `master`; Content Studio reads `draft`.
Guillotine returns validation errors	Verify the query against Guillotine 8, the application schema, variables, and project/branch endpoint. Component queries are combined, so the server log identifies the failing selection.
Page renders but a component is missing	Register the exact application-qualified descriptor and import the mappings before `fetchContent()`. Catch-all mappings do not make components production-renderable.
Content Studio preview returns 407	The token sent by XP does not match `ENONIC_API_TOKEN`, or the token is absent. Compare it with `nextjs.<name>.secret`.
Content Studio cannot contact the front end	Test the configured URL from the XP host. `localhost` refers to the XP host or container, not the editor’s computer.
Preview shows published instead of draft content	Confirm `/api/preview` enables Draft Mode and the proxy cookie is preserved. Check the `Content-Studio-Mode` header.
Internal links contain the XP site name	Check that the site segment in `ENONIC_MAPPINGS` matches the actual XP site path and render links through `getUrl()` or `RichTextView`.
Locale route loops or rewrites assets	Ensure `src/proxy.ts` excludes configured locales, API routes, Next.js internals, and all top-level public asset paths.
Published changes remain cached	Confirm the site uses Next.XP, the XP master node subscribed successfully, `/api/revalidate` is reachable, and the shared token matches.
Component preview refresh fails but full page works	Verify the component has an explicit mapping and that the catch-all layout preserves the single-component marker used by the XP proxy.

Adapter reports a missing environment variable

Define ENONIC_API, ENONIC_APP_NAME, and ENONIC_MAPPINGS before the Next.js process starts. Rebuild when changing browser-visible variables.

Content returns 404

Check the locale mapping, XP project, site path, publication state, and requested site-relative path. Direct requests read master; Content Studio reads draft.

Guillotine returns validation errors

Verify the query against Guillotine 8, the application schema, variables, and project/branch endpoint. Component queries are combined, so the server log identifies the failing selection.

Page renders but a component is missing

Register the exact application-qualified descriptor and import the mappings before fetchContent(). Catch-all mappings do not make components production-renderable.

Content Studio preview returns 407

The token sent by XP does not match ENONIC_API_TOKEN, or the token is absent. Compare it with nextjs.<name>.secret.

Content Studio cannot contact the front end

Test the configured URL from the XP host. localhost refers to the XP host or container, not the editor’s computer.

Preview shows published instead of draft content

Confirm /api/preview enables Draft Mode and the proxy cookie is preserved. Check the Content-Studio-Mode header.

Internal links contain the XP site name

Check that the site segment in ENONIC_MAPPINGS matches the actual XP site path and render links through getUrl() or RichTextView.

Locale route loops or rewrites assets

Ensure src/proxy.ts excludes configured locales, API routes, Next.js internals, and all top-level public asset paths.

Published changes remain cached

Confirm the site uses Next.XP, the XP master node subscribed successfully, /api/revalidate is reachable, and the shared token matches.

Component preview refresh fails but full page works

Verify the component has an explicit mapping and that the catch-all layout preserves the single-component marker used by the XP proxy.

Diagnostic context

Log the resolved locale, project, site, branch, render mode, content path, and front-end URL without logging the shared token. In a cluster, also confirm which XP node is master because only that node sends revalidation events.

For framework errors, use Next.js diagnostics. For GraphQL schema and query problems, use Guillotine documentation.

Troubleshooting

Contents

Common symptoms

Diagnostic context

Contents

Contents