Error: <Html> should not be imported outside of pages/_document. #77262

chrisphillers · 2025-03-18T22:27:02Z

chrisphillers
Mar 18, 2025

Link to the code that reproduces this issue

https://github.com/chrisphillers/yuzzi-film-simple

To Reproduce

Create-next-app is broken.

npx create-next-app@latest whatevernameyouwant

Enter the generated folder

npm i

npm run build

Current vs. Expected behavior

Expected result: build should complete
Actual result:

$ npm run build

[email protected] build
next build

⚠ You are using a non-standard "NODE_ENV" value in your environment. This creates inconsistencies in the project and is strongly advised against. Read more: https://nextjs.org/docs/messages/non-standard-node-env
▲ Next.js 15.2.3

Creating an optimized production build ...
✓ Compiled successfully
✓ Linting and checking validity of types
✓ Collecting page data
Error: should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
at y (.next/server/chunks/548.js:6:1351)
Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error
Error: should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page
at K (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/next/dist/compiled/next-server/pages.runtime.prod.js:16:6526)
at y (/home/chrisphillers/yuzzi-film-simple/frontend/.next/server/chunks/548.js:6:1351)
at react-stack-bottom-frame (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:8798:18)
at renderWithHooks (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:4722:19)
at renderElement (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:5157:23)
at retryNode (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:5805:22)
at renderNodeDestructive (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:5631:11)
at renderElement (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:5143:11)
at retryNode (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:5805:22)
at renderNodeDestructive (/home/chrisphillers/yuzzi-film-simple/frontend/node_modules/react-dom/cjs/react-dom-server.edge.development.js:5631:11)
Export encountered an error on /_error: /404, exiting the build.
⨯ Next.js build worker exited with code: 1 and signal: null

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
  Version: #1 SMP Tue Nov 5 00:21:55 UTC 2024
  Available memory (MB): 32061
  Available CPU cores: 16
Binaries:
  Node: 22.14.0
  npm: 10.9.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 15.2.3 // Latest available version is detected (15.2.3).
  eslint-config-next: 15.2.3
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.8.2
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

create-next-app

Which stage(s) are affected? (Select all that apply)

next build (local)

Additional context

I am not using an env in the project so no idea why I am getting the ENV warning.

However the Html error I am getting appears to be the showstopper.

I have tried multiple fresh installs and creating a seperate "not found" component to override the standard 404, no no effect.

There was an existing issue ticket for this but for some reason it was closed?

chrisphillers · 2025-03-18T22:32:40Z

chrisphillers
Mar 18, 2025
Author

A fudge to fix this strangely is to resolve the ENV error which isnt.

Updating the script to the below resolves.

"build": "NODE_ENV=production next build"

How to actually fix this issue?

0 replies

chrisphillers · 2025-03-20T01:36:58Z

chrisphillers
Mar 20, 2025
Author

Is this not a bug?

Seems like quite a few encounter this, and not resolved.

#52158

0 replies

sovetski · 2025-04-08T13:17:40Z

sovetski
Apr 8, 2025

Same here, any update please?

0 replies

icyJoseph · 2025-04-08T13:48:07Z

icyJoseph
Apr 8, 2025
Collaborator

Ah nvm, I misread, ENV for NODE_ENV... strange issue 🤔

EDIT

Can you echo, NODE_ENV? I wonder if its set in your environment, like globally and such?

0 replies

sitatel · 2025-04-18T22:16:18Z

sitatel
Apr 18, 2025

I have the same issue!!!! does this is a BIG BUG???

0 replies

davidbfrogman · 2025-05-26T13:08:23Z

davidbfrogman
May 26, 2025

I'm also seeing this issue. The NODE_ENV=production fixed it for me as well.

1 reply

agentzhao Sep 24, 2025

same here, on next 15.5.2 with turbopack. Adding NODE_ENV=production solved the issue

davidbfrogman · 2025-05-26T13:12:45Z

davidbfrogman
May 26, 2025

In fairness I did notice this, after using the solution from @chrisphillers

You are using a non-standard "NODE_ENV" value in your environment. This creates inconsistencies in the project and is strongly advised against. Read more: https://nextjs.org/docs/messages/non-standard-node-env

0 replies

FacundoCastillo12 · 2025-07-17T16:43:57Z

FacundoCastillo12
Jul 17, 2025

In my case I had the NODE_ENV set in the Windows variables, after removing it I could build with next build without problem. I comment it in case it helps someone

0 replies

emulienfou · 2025-08-01T15:32:37Z

emulienfou
Aug 1, 2025

Same issue on local and on Vercel.

Did try with/out NODE_ENV=production.
Generally when issue occurs I update all nextjs packages then issue disapears, seems to not be the case anymore.

Debugging:

▲ Next.js 15.4.2-canary.19 (Rspack) => Working build (local)
▲ Next.js 15.4.2-canary.26 (Rspack) => Failed build (local) same issue

0 replies

kenirwin · 2025-09-03T14:05:58Z

kenirwin
Sep 3, 2025

Same here -- this error appeared to crop up out of nowhere. I have no pages/ or Html or next/document called in my repo but yesterday this error popped up on build. Switching NODE_ENV to production worked, but that doesn't undermine the usefulness of having the development environment. I don't know how the server/chunks business works, but something seems to be going on there. I tried newer versions on next (i'm on 15.4.4) and moving to @latest didn't help.

My error matches other people's:

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/548.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/548.js:6:1351)
Export encountered an error on /_error: /404, exiting the build.
 ⨯ Next.js build worker exited with code: 1 and signal: null

0 replies

VictorB857 · 2025-09-21T03:34:03Z

VictorB857
Sep 21, 2025

Build without Turbopack (Next.js 15.3.0)

I hit this build error:

<Html> should not be imported outside of pages/_document.

It only happened when Turbopack was enabled. Forcing Webpack fixed it.

What I changed

package.json:

{
  "scripts": {
    "build": "TURBOPACK= npm run build:webpack",
    "build:webpack": "next build --no-lint"
  }
}

Note: TURBOPACK="0" or TURBOPACK=0 doesn’t disable it — Next does Boolean(process.env.TURBOPACK), so any non-empty string turns Turbopack on. Leaving it empty (TURBOPACK=) or unsetting it works.

How I built

rm -rf .next
npm install
npm run build  # uses Webpack via the script above

Manual run (outside the script):

unset TURBOPACK
next build --no-lint

TL;DR Build broke with Turbopack; clearing TURBOPACK to force Webpack made it pass.

0 replies

icyJoseph · 2025-09-24T11:15:01Z

icyJoseph
Sep 24, 2025
Collaborator

From reading this thread, I wonder if this comment has the key insight:

Error: <Html> should not be imported outside of pages/_document. #77262 (comment)

Somehow, NODE_ENV is set in your system.

You may try to run this in your terminal:

node -p "process.env.NODE_ENV"

That should print undefined, assuming this is the same environment where your Next.js command is being executed, then this error shouldn't happen.

If that doesn't print undefined, then you'll see some weird behaviors depending on what you are trying to do, and the value set to it.

6 replies

icyJoseph Sep 24, 2025
Collaborator

Are you seeing this in a fresh create-next-app project?

I was echoing the other comment, where they had set NODE_ENV globally, but there are other ways to potentially mess with that value too.

In the project where you see this issue, can you infer what is it getting set to? like in next.config for example, print process.env.NODE_ENV.

Thanks for responding too! Hopefully we can debug this further and have a final resolution

kenirwin Sep 24, 2025

@icyJoseph -- thanks for the clarification. I think my case must be different. I'm not seeing this on a fresh install of a next app; it cropped up in an existing project -- but checking out older versions of the before the error cropped up didn't solve it, so I wasn't able to identify a specific change that led to the problem.

icyJoseph Sep 24, 2025
Collaborator

Right, but then you should be able to add a log to collect the NODE_ENV value that's getting applied. It won't tell us what's injecting it though, but it is a start. Have you double checked your .env files? Maybe somewhere there a NODE_ENV=test, or something like that is waiting to be deleted.

kenirwin Sep 24, 2025

The situation giving rise to the error is with NODE_ENV=development -- if I switch it to production it builds fine, it's just tedious for doing actual dev work.

I'm not sure where or how to add a log for NODE_ENV at build time, but it doesn't appear that i've got NODE_ENV=test anywhere. The fact that it does work when I change NODE_ENV to production suggests that it is reading the value set in .env

icyJoseph Sep 24, 2025
Collaborator

The situation giving rise to the error is with NODE_ENV=development -- if I switch it to production it builds fine, it's just tedious for doing actual dev work.

Wait, are we still saying that, you don't set NODE_ENV at all, run next build, and this error happens.

I vibe coded this script:

// script.js
const realEnv = process.env;

function printStack(action, value) {
  const stack = new Error().stack
    .split("\n")
    .slice(2)
    .join("\n");
  console.log(`\n[HOOK] NODE_ENV ${action}: ${value}\n${stack}\n`);
}

const wrappedEnv = new Proxy({}, {
  get(_, prop) {
    if (prop === "NODE_ENV") {
      const value = realEnv.NODE_ENV;
      // printStack("read", value);
      return value;
    }
    return realEnv[prop];
  },
  set(_, prop, value) {
    if (prop === "NODE_ENV") {
      printStack("set", value);
    }
    realEnv[prop] = value;
    return true;
  },
  has(_, prop) {
    return prop in realEnv;
  },
  deleteProperty(_, prop) {
    return delete realEnv[prop];
  },
  ownKeys() {
    return Reflect.ownKeys(realEnv);
  },
  getOwnPropertyDescriptor(_, prop) {
    return Object.getOwnPropertyDescriptor(realEnv, prop);
  }
});

process.env = wrappedEnv;

I'll help us print a stack every time the value is set (I commented out the read), so you can run:

NODE_OPTIONS='--require ./script.js' npx next build

You'll see stuff like:

[HOOK] NODE_ENV set: production
    at Object.set (/Users/foo/bar/throwaway-env-error/script.js:24:7)
    at Object.callback (/Users/foo/bar/throwaway-env-error/node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/bin/next:68:34)
    at /Users/foo/bar/throwaway-env-error/node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/commander/index.js:1:15906
    at Command._chainOrCall (/Users/foo/bar/throwaway-env-error/node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/commander/index.js:1:15606)
    at /Users/foo/bar/throwaway-env-error/node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/commander/index.js:1:15884
    at Array.forEach (<anonymous>)
    at Command._chainOrCallHooks (/Users/foo/bar/throwaway-env-error/node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/commander/index.js:1:15864)
    at Command._parseCommand (/Users/foo/bar/throwaway-env-error/node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/commander/index.js:1:17032)
    at /Users/foo/bar/throwaway-env-error/node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/commander/index.js:1:14332

Here we see Next.js setting the NODE_ENV to production (pnpm dependency keys make it a bit harder to read)

Error: <Html> should not be imported outside of pages/_document. #77262

Uh oh!

Link to the code that reproduces this issue

To Reproduce

Current vs. Expected behavior

Provide environment information

Which area(s) are affected? (Select all that apply)

Which stage(s) are affected? (Select all that apply)

Additional context

Replies: 12 comments · 7 replies

Uh oh!

chrisphillers Mar 18, 2025 Author

Uh oh!

chrisphillers Mar 20, 2025 Author

Uh oh!

Uh oh!

Uh oh!

icyJoseph Apr 8, 2025 Collaborator

EDIT

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Build without Turbopack (Next.js 15.3.0)

What I changed

How I built

Uh oh!

Uh oh!

icyJoseph Sep 24, 2025 Collaborator

Uh oh!

Uh oh!

icyJoseph Sep 24, 2025 Collaborator

Uh oh!

Uh oh!

icyJoseph Sep 24, 2025 Collaborator

Uh oh!

Uh oh!

icyJoseph Sep 24, 2025 Collaborator

Replies: 12 comments 7 replies

chrisphillers
Mar 18, 2025
Author

chrisphillers
Mar 20, 2025
Author

icyJoseph
Apr 8, 2025
Collaborator

icyJoseph
Sep 24, 2025
Collaborator

icyJoseph Sep 24, 2025
Collaborator

icyJoseph Sep 24, 2025
Collaborator

icyJoseph Sep 24, 2025
Collaborator