Issue Station
Sign In
Tools hereToolbox

nextjs - 💡(How to fix) Fix App Router export: "<Html> should not be imported outside of pages/_document" for /404 and /500 (no next/document in userland) [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#83784•Fetched 2026-04-08 02:21:31
View on GitHub
Comments
1
Participants
2
Timeline
4
Reactions
0
Author
cfisher8565cfisher8565
Participants
cfisher8565cfisher8565github-actions[bot]github-actions[bot]
Timeline (top)
closed ×1commented ×1labeled ×1locked ×1

Error Message

Export encountered errors on following paths: /404 /500

Error: <Html> should not be imported outside of pages/_document. Read more: https://nextjs.org/docs/messages/no-document-import-in-page at .../node_modules/next/dist/compiled/next-server/pages.runtime.prod.js:16:5430 at .../.next/server/chunks/1682.js:6:1263 (or 6859.js on subsequent builds)

Fix Action

Fix / Workaround

Ask

Is this a known export-only status-page quirk for App Router, or a bug? Any workaround to suppress/fix these warnings without reverting to the Pages router for status pages?

Code Example

> Export encountered errors on following paths:
  /404
  /500

Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at .../node_modules/next/dist/compiled/next-server/pages.runtime.prod.js:16:5430
    at .../.next/server/chunks/1682.js:6:1263 (or 6859.js on subsequent builds)

---

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

---

export default function NotFound() {
  return <div>Not found</div>
}

---

"use client"
export default function GlobalError({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <html>
      <body>
        <div>Application error</div>
        <button onClick={reset}>Try again</button>
      </body>
    </html>
  )
}

---

> Export encountered errors on following paths:
  /404
  /500
Error: <Html> should not be imported outside of pages/_document.
    at .../pages.runtime.prod.js:16:5430
    at .../.next/server/chunks/1682.js:6:1263
RAW_BUFFERClick to expand / collapse

What version of Next.js are you using?

14.2.32

What version of Node.js are you using?

20.x (CI), 24.x (local)

What browser are you using?

N/A (build-time)

What operating system are you using?

macOS/Ubuntu (repro on both)

Describe the Bug

When using the App Router with a standard root layout (returning <html> and <body>), next build succeeds but static export reports errors for status pages only:

> Export encountered errors on following paths:
  /404
  /500

Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at .../node_modules/next/dist/compiled/next-server/pages.runtime.prod.js:16:5430
    at .../.next/server/chunks/1682.js:6:1263 (or 6859.js on subsequent builds)

There is no next/document (Html/Head/Main/NextScript) import in userland. The stack points to Next internal pages runtime. All non-status routes build and export fine.

Expected Behavior

No export errors for /404 and /500 when using App Router status pages (app/not-found.tsx, app/error.tsx/app/global-error.tsx).

To Reproduce

Minimal setup (App Router only):

  1. npx create-next-app@latest --ts (App Router)
  2. Add app/layout.tsx:
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}
  1. Add app/not-found.tsx:
export default function NotFound() {
  return <div>Not found</div>
}
  1. Add app/global-error.tsx (client):
"use client"
export default function GlobalError({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <html>
      <body>
        <div>Application error</div>
        <button onClick={reset}>Try again</button>
      </body>
    </html>
  )
}
  1. next build

Observed: build succeeds, but export reports errors only for /404 and /500 with the message above, even though no next/document is imported anywhere.

Notes

  • Adding a minimal pages/_document.tsx does not change the outcome.
  • Adding minimal pages/404.tsx and pages/500.tsx still shows the same export warnings, now listing /404 and /500 explicitly.
  • App otherwise runs fine; this seems limited to export status pages.

Environment bits

  • next.config: output: 'standalone', experimental.optimizeCss: true (repro without too)
  • No custom Document or Head/Html imports in App Router files

Logs excerpt

> Export encountered errors on following paths:
  /404
  /500
Error: <Html> should not be imported outside of pages/_document.
    at .../pages.runtime.prod.js:16:5430
    at .../.next/server/chunks/1682.js:6:1263

Ask

Is this a known export-only status-page quirk for App Router, or a bug? Any workaround to suppress/fix these warnings without reverting to the Pages router for status pages?

Thanks!

extent analysis

TL;DR

The issue can be resolved by creating a custom pages/_document.tsx file that extends the Html component from next/document to properly handle the App Router status pages during static export.

Guidance

  • The error message suggests that the Html component is being imported outside of pages/_document, which is not allowed in Next.js. However, the code provided does not show any direct imports of next/document.
  • The issue seems to be related to the App Router and static export, as the build process succeeds but export reports errors for status pages only.
  • To mitigate this issue, try creating a minimal pages/_document.tsx file that extends the Html component from next/document, as suggested in the error message.
  • Verify that the custom pages/_document.tsx file resolves the export errors for the status pages.

Example

// pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Notes

  • The provided code snippets and error messages suggest that the issue is specific to the App Router and static export, and may not be related to the Node.js or browser versions.
  • The next.config settings, such as output: 'standalone' and experimental.optimizeCss: true, may also be contributing to the issue, but their impact is unclear without further investigation.

Recommendation

Apply a workaround by creating a custom pages/_document.tsx file to handle the App Router status pages during static export, as this seems to be the most direct way to resolve the export errors.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#agent execution#callback error#memory management#API rate limit#retriever error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING