Insight Error Page

Insight Error Page — Write & Audit

Write or audit an errors/<slug>.mdx insight-kind page that ships from this repo to nextjs.org and mirrors the fix-card set in the Next.js dev overlay.

Terminology: the frontmatter uses kind: insight but the body text calls these "errors" — never "insights". Write "this error", "error pages", "dismiss the error".

When to use this skill

• Write mode: "create the error page for next-prerender-random", "write the sync IO docs"
• Audit mode: "audit the blocking-prerender-dynamic page", "check the error pages match the framework"
• Any task involving errors/*.mdx insight pages (frontmatter has kind: insight)

Source of truth chain

Every decision traces back to one of these. When in doubt, read the source — don't guess.

Before you start

1. Read the framework card data for the error family you're writing. Find the matching FixCard[] in instant-guidance-data.ts. Note every card's id, title, group, link, and snippets.
2. Read the factory message that produces the dev-overlay headline. Find createSyncIOError, createSyncIOClientError, createDynamicBodyError, etc. The headline template (minus the Route "..." prefix) becomes the page title.
3. Read the existing errors/<slug>.mdx if it exists. Note every pattern, code example, and caveat. You must preserve all useful content — relocate it if the new structure doesn't have a 1:1 slot for it.
4. Read the canonical docs for every API you'll reference: use cache, cacheLife, cacheTag, connection, Suspense, useEffect, use client, generateStaticParams, etc. Use the exact terminology from the published docs.
5. Apply Vercel technical writing style (active voice, sentence-case headings, no banned words). The full vercel-technical-writing skill lives in vercel/front; the condensed rules below are the minimum bar.

Page structure (mandatory)

Every page follows this exact shape. Do not add, remove, or reorder sections.

---
title: <literal dev-overlay headline, no period, strip Route "..." prefix>
kind: insight
---

<the Instant Navigations callout div — the styled box linking the blog post and the Ensuring instant navigations guide; copy it from any existing insight page>

<Framing, 2-3 paragraphs. Paragraph 1 opens "During <phase>, <event>" in past tense (e.g. "During prerendering, a Server Component called ..."), names the APIs, and states the mechanism or consequence. Never open a paragraph with inline code — lead with a word ("The `params` prop ..."). Later paragraphs carry the teaching and cross-link sibling pages (parallel API families + client/server counterpart) using the "For X, see Y" formula.>

## Ways to fix this

<FixCardGrid> wrapping one <FixCard /> per framework card, in framework order

## <Card 1 title>
  Choose this fix when ...
  ### Patterns
  ### Trade-off
  ### Gotchas
  (optional: ### Short-lived caches — only for cache fixes)

## <Card 2 title>
  ...

## <Card N title>
  ...

(optional: ## Other options — for useful patterns that don't map to a framework fix card but are still relevant. Examples: bridging to a different error page's fix ("Cache the value in a Server Component" on a client page, linking to the server page), upstream content from `errors/<slug>.mdx` that doesn't fit the card structure, alternative APIs that sidestep the problem entirely. Each option gets its own `###` heading with framing prose, a code snippet, and a "Learn more" link to the page that covers it in full.)

## Verifying the fix
  (canonical two paragraphs — see "Verifying the fix" rule below)

## Don't want this validation?
  (canonical opt-out block — see "Don't want this validation?" rule below.
   Exception: sync-IO pages replace this with "## Why `instant = false` doesn't clear this error",
   because the opt-out cannot suppress sync-IO aborts.)

## Related Insights
  (full list of every other insight-kind error page, current page omitted)

Rules (hard requirements)

Frontmatter

• title = the dev-overlay display headline, no period. That is the string the overlay shows (see the headline strings in errors.tsx / the factory in e.g. sync-io-messages.ts), with the Route "..." prefix stripped and any inline expression genericized (the client-hook overlay shows `useSearchParams()` inline; its docs title says "in a Client Component" instead).
• kind: insight — always present.

Verifying the fix

Every page has a ## Verifying the fix section before the opt-out block. No page has a top-level Good to know; page-specific tips go in Gotchas under the relevant fix section. Two canonical paragraphs:

1. The observable check: "After applying a fix, reload the route and confirm the page immediately paints meaningful UI, with any <Suspense> fallbacks covering only the regions that stream in." (navigation insights say "navigate to the route and confirm the insight no longer appears in the dev overlay and ..." instead of "reload the route"). Followed by the empty-shell caveat sentence: a boundary around the whole page body can pass validation with an empty shell.
2. The tooling paragraph: dev overlay points at the failing component; from a build, the output is more abbreviated. Run next build --debug-prerender for full user-frame stack traces and next build --debug-build-paths /dashboard /settings to iterate on specific routes. Copy the exact wording from an existing page.

State the check as what the reader sees in the browser, not as framework artifacts ("the static shell renders real content" was retired for this reason — a fallback is expected after a correct fix; the check is that it covers only the streamed region).

<FixCard> cards

• Wrap all cards in a single <FixCardGrid> (the same component used in docs/01-app/02-guides/instant-navigation.mdx).
• One <FixCard /> per framework card, in the same order as the framework FixCard[] array.
• title = card title from framework, verbatim. If it reads awkward as a heading, change the framework first — never the docs.
• href = # + the auto-slug of the title (e.g. "Generate on every request" → #generate-on-every-request). This must match what the heading auto-generates.
• group = card group from framework (dynamic, cache, client, stream, defer, measure, block, render, ignore, upgrade, disable, static).
• snippets = the same snippets array as the matching framework FixCard in instant-guidance-data.ts. Copy it verbatim. No description prose lives on the card — the snippets carry the visual.
• Self-close the tag (<FixCard ... />). The card has no children.
• No prompt prop. The "Copy prompt" button builds the prompt dynamically at click time from the page URL and the card's title + href. The agent receives a prompt that points at the rule docs and names the fix — it then reads the docs page (the same one the user is on) for every constraint and code shape. That is why this skill exists: the docs page itself is the prompt's source of truth.

## <Fix> sections

• Heading text = card title, verbatim. Auto-slugs to the href above.
• Opens with: "Choose this fix when <condition>."
• ### Patterns — one #### per meaningfully different shape of the fix. Each has:
  • 1–2 sentences of plain-prose framing
  • One short, readable jsx filename="app/..." snippet (complete, copy-paste-ready, no ...existing code...)
  • Optional Learn more: link below the snippet
• ### Trade-off — 1 paragraph. Mandatory. Describe the trade-off in the context of this error, not the generic API trade-off. If the only honest trade-off is the canonical API behavior (e.g. "GSP requires a rebuild when the list changes"), keep it to one sentence and link out to the API reference. Don't repeat what the API reference page already covers.
• ### Gotchas — bulleted list. Mandatory (at least 1 bullet).
• Optional ### Short-lived caches subsection for cache fixes (document the 5-minute threshold).

Code snippets

• Must be valid React. Do not show unstable APIs (random, time, crypto) inline during render in a Client Component — that causes a hydration mismatch. Defer to useEffect + useState or an event handler.
• Lazy useState initializers (e.g. useState(() => someUnstableCall())) run during SSR — warn against this in Gotchas.
• useRef lazy-init pattern is valid for stable IDs (initialize in a getter function, not inline). Only applicable when the value should be computed once and frozen — not when it should reflect the current moment.
• Always include filename="app/..." on code blocks.
• When a pattern defers rendering to after hydration (e.g. useEffect), the Trade-off must link to Preventing flash before hydration.

Cross-links

• Framing paragraph: link to sibling pages (client ↔ server counterpart, parallel API families).
• Gotchas: link to the -client page when warning about inline render in Client Components.
• Related Insights: the full list of every other insight-kind error page, current page omitted. This is an index of the Insight family, not a curated short list. Order: body errors → metadata/viewport → unstable-value errors (server then client) → navigation Insights. Do not add API references or guides to this section; those belong inline in the body where relevant.
• Every API reference and file convention must be inline-linked throughout, not reserved for the Related Insights section.
• Cross-page pattern linking: When a fix on one page is covered in depth on a sibling page, show only the most common pattern inline and link out to the sibling for the full set. For example, a server page's "Render on the client" fix shows one client pattern and links to the -client page; a client page's "Other options" section bridges to the server page's cache fix. Don't duplicate entire sections across sibling pages — keep each page lean and let the sibling be the canonical reference.
• First-party only: link only to nextjs.org/docs/*, react.dev/*, developer.mozilla.org/*, and other canonical first-party references. Never link to personal blogs, community write-ups, conference talks, X/Bluesky posts, GitHub gists, or any third-party source — including the page author's own blog. If a third-party post inspired a pattern, internalize the idea and write it in our own voice without citation. Sibling error pages, our own docs, and primary API specs are the only acceptable destinations.

Terminology (verify against canonical docs)

• use cache directive (not "use cache" in prose)
• Cache Components (capitalized)
• static shell (link to /docs/app/glossary#static-shell)
• instant (not instant)
• cacheLife / cacheTag / revalidateTag / updateTag — use published names exactly
• connection() from next/server
• Client Component / Server Component (capitalized)
• prerendering — always linked on first use