Troubleshooting
Developer preview
This feature is in developer preview. Use with caution as it may change unexpectedly. For more information, contact us.
Find your problem in the tables below. Each row gives the frequent causes and the fix. Then use the debugging tools to find the cause.
Pages and routes#
| Problem | Cause | Fix |
|---|---|---|
| The page gives a 404. | The composition is not published, or the project map node has no composition. | Publish the composition. Attach it to the node of the path. |
| The page gives a 404, but the composition is published. | The path in the browser is different from the project map path, for example /en/about and /en-US/about. | Change the path in rewriteRequestPath of the middleware. Refer to Middleware configuration. |
| A page in an ordinary Next.js route gives a 404. | No Next.js route matches the path of the project map node. | Add a route for each project map node that has a composition. |
| The page shows "Component not found: hero". | resolveComponent has no entry for the component type, or the public ID is different. | Add the type to resolveComponent. Use the public ID from the component library. |
| A slot or a region is empty. | The slot name in your code is different from the public ID of the slot. | Use the public ID of the slot, for example slots.content. |
| A component with visibility rules is not in the server HTML. | This is expected. Visibility rules run only in the browser. | Do not put content for search engines in a component with visibility rules. |
| A redirect gives 308, not 301. | Next.js sends 308 for permanentRedirect() and 307 for redirect(). | No fix. Next.js does not keep the exact status code. |
The route builds as dynamic (ƒ), not static (●). | The page reads searchParams, cookies() or headers() on published requests. | Read them only in draft mode. The middleware writes the request state into the code. |
The build fails with an error about an empty generateStaticParams. | Cache Components is on, and generateStaticParams returns []. | Return at least one code, for example createUniformStaticParams({ paths: ["/"] }). |
Preview and Canvas#
| Problem | Cause | Fix |
|---|---|---|
The preview gives 401 No preview secret is configured. | UNIFORM_PREVIEW_SECRET is not set in the app. | Set it, and start the server again. |
The preview gives 401 Invalid preview secret. | The secret in the preview URL is different from UNIFORM_PREVIEW_SECRET. | Use the same value in the two places. |
| The preview gives a 404. | Canvas sends the project map path, and the app has no route for it. For example, Canvas sends /en-US/about, and the site uses /en/about. | Change the path in resolveFullPath of the preview handler. Refer to Preview. |
| The pattern preview gives a 404. | The playground route is not at playgroundPath, or processPlaygroundPath changes the path. | Put the playground page at ${playgroundPath}/[code]. Do not change the path with processPlaygroundPath. |
| The pattern preview shows "Not Found: page". | The pattern is a composition pattern, and its root type is not in resolveComponent. This occurs with hybrid pages. | Render page-type patterns with your region wrapper. Refer to Hybrid pages. |
| The preview shows published content. | The middleware is proxy.ts, or it is not on the edge runtime. On Vercel, the SDK cannot read draft mode there. | Use middleware.ts with runtime: "experimental-edge". |
| Canvas cannot select the components. | The URL does not have is_incontext_editing_mode=true, so the page is in the draft state, not the editor state. | Open the composition from Canvas. Canvas adds the query string. |
| Canvas selects the wrong component, or the markers occur two times. | The page renders the same composition more than one time. | Render each composition one time on a page. Use one UniformContext for the page. |
| The text edit in Canvas does nothing. | The component renders the parameter value directly, not with UniformText. | Render text parameters with UniformText. |
Personalization and edge mode#
| Problem | Cause | Fix |
|---|---|---|
| The visitor sees the default variant first, and then a different variant. | This is lite mode. The browser chooses the variants after hydration. | Use edge mode. Refer to Edge mode execution. |
| Edge mode shows the default variant for a new signal. | The manifest of the edge does not have the new signal yet. | Publish the manifest. On Vercel, the manifest.published webhook must reach the preview route with onRevalidateTags: expireVercelRuntimeCacheTags. With a manifest in the build, build again. |
Edge mode does not work under next dev. | Edge mode needs published pages from the cache. | Use a production build: npm run build && npm run start. |
| Edge mode does not work in the Canvas preview. | This is expected. Draft requests do not use edge mode. | No fix. The browser chooses the variants in preview. |
| A page under a dynamic project map node stays without edge processing. | The edge route store recorded the page without placements, and the webhook expires only the static part of the path. | Set a ttl in vercelEdgeRouteStore({ ttl }), or use a filter that does not skip the page. |
A new signal or test does not work under next dev. | UniformContext gets the manifest with force-cache, also in development. | Do a hard reload, or delete the .next folder. |
curl gets all variants, or the default variant. | The request is not a document request for the middleware. | Send Accept: text/html, or no Accept header. |
Content updates and webhooks#
| Problem | Cause | Fix |
|---|---|---|
| A published change does not show on the site. | No webhook is configured, or it does not reach the app. | Add a webhook for /api/preview. Refer to Caching. |
| The first request after a publish shows the old content. | This is expected. Next.js serves the old page and renders the new page in the background. | Load the page again. |
The webhook answers 401. | The secret query string or the Svix signature is not correct. | Use the same value as UNIFORM_PREVIEW_SECRET. Use the signing secret of the webhook in UNIFORM_WEBHOOK_SECRET. |
The webhook answers { "handled": false }. | The handler does not use this event. | Select only the events in Configure the webhook. |
revalidatePath("/about") does nothing. | The middleware rewrites /about to /uniform/[code]. With a rewrite, revalidatePath must get the destination route. | Use revalidateTag("path:/about", "max"). |
Install, build and types#
| Problem | Cause | Fix |
|---|---|---|
npm shows ERESOLVE for a @uniformdev package. | A peer dependency range does not include the developer preview version. | Add "overrides": { "@uniformdev/context": "$@uniformdev/context" } to package.json. |
The browser Context does not work, or hooks return undefined. | Two versions of @uniformdev/context are installed. | Use the same version for all @uniformdev packages. Run npm ls @uniformdev/context to find the copies. |
Next.js shows a warning that middleware.ts is deprecated, or that the edge runtime is deprecated. | This is expected. | Keep middleware.ts with runtime: "experimental-edge". |
TypeScript shows an error for parameter={title} on UniformText. | The parameter is optional, but the parameter prop is required. | Render the component only when the parameter exists: {title ? <UniformText … /> : null}. |
Debugging tools#
Read the code of a request#
The middleware rewrites each request to /uniform/[code]. To see the values in the code, add a log to the composition route in development:
app/uniform/[code]/page.tsx
import { deserializePageState, UniformComposition, type UniformPageParameters } from "@uniformdev/next-app-router";
import { resolveComponent } from "@/components/resolveComponent";
export default async function UniformPage(props: UniformPageParameters) {
const { code } = await props.params;
if (process.env.NODE_ENV === "development") {
console.log(deserializePageState({ code }));
}
return <UniformComposition code={code} resolveComponent={resolveComponent} />;
}
The log shows the PageState:
| Field | Look for |
|---|---|
routePath | The path that the Route API gets. Is it the project map path? |
compositionState | 64 published, 0 draft, 63 editor. Is draft mode on? |
edgeMode | true when the edge processes the page. |
defaultConsent, locale, releaseId, keys | The values from the middleware options. |
Look at the response headers#
curl -sI http://localhost:3000/about
| Header | Meaning |
|---|---|
cache-control: private, no-store | The edge processed the page, and sent it with the visitor state and without an ETag. |
cache-control: private, no-cache with etag | The edge processed the page. The browser can get 304 next time. |
x-nextjs-cache: HIT, STALE or MISS | The page came from the Next.js cache, from an old cache entry, or from a new render. |
To see the cached page without the edge, send the origin header:
curl -sI -H "x-uniform-edge-origin: 1" http://localhost:3000/uniform/<code>
Look at the visitor state from the edge#
In edge mode, the middleware writes the visitor state into the __UNIFORM_DATA__ script:
curl -s "http://localhost:3000/?utm_campaign=launch" | grep -o '__UNIFORM_DATA__[^<]*'
The script contains the scores (ssv), the tests and the personalization variants of the visitor. It is empty when the response has an ETag.
Use the Uniform Context DevTools#
The default client context turns on the Uniform Context DevTools, unless context.disableDevTools is true in the server configuration. With the DevTools, you can see and change the scores, quirks and tests of the visitor in the browser. When you change them, the page refreshes. Refer to Context DevTools.
Look at the cookies#
| Cookie | Meaning |
|---|---|
__prerender_bypass | Next.js draft mode is on. The preview handler sets it. |
ufvd | The visitor data of the Uniform Context. |
ufqc | Quirks from the middleware. It expires after 10 seconds. |
To turn off draft mode, open /api/preview?disable=true&path=/.
Look at the webhook response#
The webhook handler answers with the tags and paths that it revalidated:
{ "handled": true, "tags": ["composition:6c4f…", "path:/about"], "paths": ["/about"] }