nextjs - 💡(How to fix) Fix Next.js 15.5.x: App Router standalone build fails with '<Html> should not be imported outside of pages/_document' during /404 and /500 prerender [1 comments, 2 participants]

Q: Expected behavior

Build should succeed. The App Router `not-found.tsx` should be used for `/404` and no Pages Router `_error` prerender should occur.

nextjs2026-02-23 02:25:47

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.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

vercel/next.js#90349•Fetched 2026-04-08 00:20:21

View on GitHub

Comments

Participants

Timeline

Reactions

Author

spyd3r83

Participants

github-actions[bot]

spyd3r83

Timeline (top)

closed ×1commented ×1labeled ×1locked ×1

A pure App Router project with output: 'standalone' fails to build on Next.js 15.5.12 with:

Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at x (.next/server/chunks/449.js:6:1351)
Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered an error on /_error: /404, exiting the build.

The error alternates between /404 and /500 on successive builds. The project has no pages/ directory whatsoever — it is a pure App Router application.

Error Message

Error: <Html> should not be imported outside of pages/_document. Read more: https://nextjs.org/docs/messages/no-document-import-in-page at x (.next/server/chunks/449.js:6:1351) Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error Export encountered an error on /_error: /404, exiting the build.

Root Cause

Build fails during "Generating static pages" phase. Next.js tries to prerender /404 and /500 by running the Pages Router /_error export path (moveExportedPage('/_error', '/404', ...)), which internally invokes the Html component from pages/_document. This component calls useHtmlContext(), which throws when HtmlContext is undefined because there is no Pages Router Document context set up.

Code Example

Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at x (.next/server/chunks/449.js:6:1351)
Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered an error on /_error: /404, exiting the build.

---

// If there's /not-found inside app, we prefer it over the pages 404
if (hasStaticApp404) {
    await moveExportedAppNotFoundTo404();
} else {
    if (!hasPages404 && !hasApp404 && useStaticPages404) {
        await moveExportedPage('/_error', '/404', '/404', false, 'html');
    }
}

---

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'standalone',
  reactStrictMode: true,
  experimental: {
    serverActions: {
      bodySizeLimit: '10mb',
    },
  },
  env: {
    NEXT_PUBLIC_VENDURE_SHOP_API_URL: process.env.NEXT_PUBLIC_VENDURE_SHOP_API_URL,
    // ...other NEXT_PUBLIC_ vars
  },
};

export default nextConfig;

---

import Link from 'next/link';
import { Header } from '@/components/header';
import { Footer } from '@/components/footer';

export default function NotFound() {
  return (
    <>
      <Header />
      <main className="flex-1 flex items-center justify-center py-24">
        <div className="text-center">
          <h1 className="text-6xl font-bold text-brand-500 mb-4">404</h1>
          <h2 className="text-2xl font-semibold text-foreground mb-4">Page Not Found</h2>
          <p className="text-muted mb-8 max-w-md mx-auto">
            The page you&apos;re looking for doesn&apos;t exist or has been moved.
          </p>
          <Link href="/" className="...">Back to Home</Link>
        </div>
      </main>
      <Footer />
    </>
  );
}

---

'use client';

export default function GlobalError() {
  return (
    <html lang="en" className="dark">
      <body className="...">
        <h1>500</h1>
        <h2>Something Went Wrong</h2>
        <a href="/">Back to Home</a>
      </body>
    </html>
  );
}

---

▲ Next.js 15.5.12
- Experiments (use with caution):
  · serverActions

Creating an optimized production build ...
✓ Compiled successfully in 16.4s
  Linting and checking validity of types ...
  Collecting page data ...
  Generating static pages (0/23) ...
Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at x (.next/server/chunks/449.js:6:1351)
Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error
Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at x (.next/server/chunks/449.js:6:1351)
Export encountered an error on /_error: /404, exiting the build.
⨯ Next.js build worker exited with code: 1 and signal: null

RAW_BUFFERClick to expand / collapse

Summary

A pure App Router project with output: 'standalone' fails to build on Next.js 15.5.12 with:

Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at x (.next/server/chunks/449.js:6:1351)
Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered an error on /_error: /404, exiting the build.

The error alternates between /404 and /500 on successive builds. The project has no pages/ directory whatsoever — it is a pure App Router application.

Reproduction steps

Pure App Router project (src/app/ directory, no pages/ directory)
next.config.ts with output: 'standalone'
src/app/not-found.tsx exists (App Router custom 404)
src/app/global-error.tsx exists (App Router global error boundary — has <html> and <body> tags as required by Next.js docs)
Run next build

Expected behavior

Build should succeed. The App Router not-found.tsx should be used for /404 and no Pages Router _error prerender should occur.

Actual behavior

From build/index.js the condition that should skip this path:

// If there's /not-found inside app, we prefer it over the pages 404
if (hasStaticApp404) {
    await moveExportedAppNotFoundTo404();
} else {
    if (!hasPages404 && !hasApp404 && useStaticPages404) {
        await moveExportedPage('/_error', '/404', '/404', false, 'html');
    }
}

hasApp404 = !!(mappedAppPages?.['/_not-found/page']) — this is true because not-found.tsx exists.

hasStaticApp404 = hasApp404 && isApp404Static where isApp404Static = staticPaths.has(UNDERSCORE_NOT_FOUND_ROUTE_ENTRY).

Hypothesis: isApp404Static is false — either /_not-found/page is not being added to staticPaths, or it's being classified as dynamic — causing the build to fall through to the /_error export path which then crashes.

Environment


Next.js	`15.5.12`
React	`19.2.4`
Node.js	`20.20.0` (inside Docker)
OS	Linux (Docker container, `node:20-alpine`-based image)
Package manager	`pnpm`

`next.config.ts`

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'standalone',
  reactStrictMode: true,
  experimental: {
    serverActions: {
      bodySizeLimit: '10mb',
    },
  },
  env: {
    NEXT_PUBLIC_VENDURE_SHOP_API_URL: process.env.NEXT_PUBLIC_VENDURE_SHOP_API_URL,
    // ...other NEXT_PUBLIC_ vars
  },
};

export default nextConfig;

`src/app/not-found.tsx`

import Link from 'next/link';
import { Header } from '@/components/header';
import { Footer } from '@/components/footer';

export default function NotFound() {
  return (
    <>
      <Header />
      <main className="flex-1 flex items-center justify-center py-24">
        <div className="text-center">
          <h1 className="text-6xl font-bold text-brand-500 mb-4">404</h1>
          <h2 className="text-2xl font-semibold text-foreground mb-4">Page Not Found</h2>
          <p className="text-muted mb-8 max-w-md mx-auto">
            The page you&apos;re looking for doesn&apos;t exist or has been moved.
          </p>
          <Link href="/" className="...">Back to Home</Link>
        </div>
      </main>
      <Footer />
    </>
  );
}

Header is a 'use client' component (uses useState/useEffect).

`src/app/global-error.tsx`

'use client';

export default function GlobalError() {
  return (
    <html lang="en" className="dark">
      <body className="...">
        <h1>500</h1>
        <h2>Something Went Wrong</h2>
        <a href="/">Back to Home</a>
      </body>
    </html>
  );
}

Full build output

▲ Next.js 15.5.12
- Experiments (use with caution):
  · serverActions

Creating an optimized production build ...
✓ Compiled successfully in 16.4s
  Linting and checking validity of types ...
  Collecting page data ...
  Generating static pages (0/23) ...
Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at x (.next/server/chunks/449.js:6:1351)
Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error
Error: <Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
    at x (.next/server/chunks/449.js:6:1351)
Export encountered an error on /_error: /404, exiting the build.
⨯ Next.js build worker exited with code: 1 and signal: null

Additional notes

No pages/ directory exists anywhere in the project
No user code imports Html, next/document, or pages/_document
The error is thrown inside Next.js's own Html component (chunk 449.js, confirmed to contain the Pages Router _document implementation)
Clearing .next cache has no effect
The build compiled successfully — the failure occurs at the static page generation phase only
This regression is specific to 15.5.x — the project was previously on ^15.1.0

extent analysis

Quick Fix

Make the App Router not‑found.tsx (and optionally global-error.tsx) a forced‑static page.
Add the static‑generation hint that Next 15’s

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?

FAQ

Expected behavior

Build should succeed. The App Router not-found.tsx should be used for /404 and no Pages Router _error prerender should occur.

#api #ssr #installation #tensor shape #autograd error #dependency conflict #environment setup #docker error #permission error

Still need to ship something?

×6

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

Data

Security

Network

Code

UI/UX

Text

System

Multimedia

Protocol

API

Engineering

nextjs - 💡(How to fix) Fix Next.js 15.5.x: App Router standalone build fails with '<Html> should not be imported outside of pages/_document' during /404 and /500 prerender [1 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Code Example

Summary

Reproduction steps

Expected behavior

Actual behavior

Environment

`next.config.ts`

`src/app/not-found.tsx`

`src/app/global-error.tsx`

Full build output

Additional notes

extent analysis

Quick Fix

FAQ

Expected behavior

Still need to ship something?

TRENDING

nextjs - 💡(How to fix) Fix Next.js 15.5.x: App Router standalone build fails with '<Html> should not be imported outside of pages/_document' during /404 and /500 prerender [1 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Code Example

Summary

Reproduction steps

Expected behavior

Actual behavior

Environment

next.config.ts

src/app/not-found.tsx

src/app/global-error.tsx

Full build output

Additional notes

extent analysis

Quick Fix

FAQ

Expected behavior

Still need to ship something?

RELATED_DISCOVERY

TRENDING

`next.config.ts`

`src/app/not-found.tsx`

`src/app/global-error.tsx`