Mintlify can't start when using node 25

mint dev

/usr/local/lib/node_modules/mint/node_modules/@typescript/vfs/dist/vfs.cjs.development.js:25 var shouldDebug = hasLocalStorage && /#PURE/localStorage.getItem("DEBUG") || hasProcess && process.env.DEBUG; ^

TypeError: localStorage.getItem is not a function at Object. (/usr/local/lib/node_modules/mint/node_modules/@typescript/vfs/dist/vfs.cjs.development.js:25:64) at Module._compile (node:internal/modules/cjs/loader:1759:14) at Object..js (node:internal/modules/cjs/loader:1892:10) at Module.load (node:internal/modules/cjs/loader:1479:32) at Module._load (node:internal/modules/cjs/loader:1298:12) at TracingChannel.traceSync (node:diagnostics_channel:328:14) at wrapModuleLoad (node:internal/modules/cjs/loader:244:24) at Module.require (node:internal/modules/cjs/loader:1502:12) at require (node:internal/modules/helpers:152:16) at Object. (/usr/local/lib/node_modules/mint/node_modules/@typescript/vfs/dist/index.js:7:20)

Node.js v25.0.0

Oct 21 '25 09:10 rafipiccolo

same for us, I duct taped it with docker for now

in our case we have a monorepo with the mintlify docs at /apps/docs, you need to change that according to your location

 docker run --rm -it \
  -p 3000:3000 \
  -v "$(pwd):/project" \
  -w /project/apps/docs \
  node:24 \
  npx --yes mint@latest dev

Nov 05 '25 08:11 chronark

Hit this bug, while evaluating mintlify. Not a good start for me.

Nov 06 '25 01:11 mmichie

Mintlify fails out of the box for me, fresh install with "mint new docs && cd docs" produces a broken setup:

% mint --version 4.2.188

% node --version v25.1.0

% mint dev ⨯ [TypeError: localStorage.getItem is not a function] ⨯ TypeError: Invalid URL at u.getInitialProps (.next/server/pages/_error.js:1:895) at async x (.next/server/pages/_error.js:1:3357) at async v (.next/server/pages/_error.js:1:7128) at async U (.next/server/pages/_error.js:1:10047) { code: 'ERR_INVALID_URL', input: '/' } ⨯ TypeError: Invalid URL at u.getInitialProps (.next/server/pages/_error.js:1:895) at async x (.next/server/pages/_error.js:1:3357) at async v (.next/server/pages/_error.js:1:7128) at async U (.next/server/pages/_error.js:1:10047) { code: 'ERR_INVALID_URL', input: '/' } ⨯ [TypeError: localStorage.getItem is not a function] { page: '/' } (node:40567) Warning: --localstorage-file was provided without a valid path (Use node --trace-warnings ... to show where the warning was created) [TypeError: localStorage.getItem is not a function] { page: '/' } [TypeError: localStorage.getItem is not a function] { page: '/' } ⨯ [TypeError: localStorage.getItem is not a function] { page: '/' } ⨯ TypeError: Invalid URL at u.getInitialProps (.next/server/pages/_error.js:1:895) at async x (.next/server/pages/_error.js:1:3357) at async v (.next/server/pages/_error.js:1:7128) at async U (.next/server/pages/_error.js:1:10047) { code: 'ERR_INVALID_URL', input: '/favicon.ico' } ⨯ TypeError: Invalid URL at u.getInitialProps (.next/server/pages/_error.js:1:895) at async x (.next/server/pages/_error.js:1:3357) at async v (.next/server/pages/_error.js:1:7128) at async U (.next/server/pages/_error.js:1:10047) { code: 'ERR_INVALID_URL', input: '/favicon.ico' } ⨯ [TypeError: localStorage.getItem is not a function] { page: '/favicon.ico' } [TypeError: localStorage.getItem is not a function] { page: '/favicon.ico' } [TypeError: localStorage.getItem is not a function] { page: '/favicon.ico' } ✓ preview ready

local → http://localhost:3000 network → http://192.168.1.115:3000

press ctrl+c to exit the preview

Nov 09 '25 04:11 dweekly

++ Getting the same issue with the same versions for our monorepo

Nov 10 '25 22:11 abhi-arya1

Node JS version 25 introduced breaking changes to the Web Storage API's. Specifically localStorage.getItem. Node 25 is currently creating localStorage as an empty proxy object which lead to these errors.

The best workaround is using an lts version of nodejs through either nvm/ fnm or your native package manager and explictily install the lts 22 or 20 versions of nodejs.

Related issues:

https://github.com/nodejs/node/issues/60303
https://github.com/vitest-dev/vitest/issues/8757

Nov 10 '25 23:11 cdxker

Workaround: https://github.com/capricorn86/happy-dom/issues/1950#issuecomment-3523878228

Nov 12 '25 20:11 brianhelba

node 25 TypeError: localStorage.getItem is not a function

mint dev