node 25 TypeError: localStorage.getItem is not a function

[rafipiccolo]

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

[chronark]

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

[mmichie]

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

[dweekly]

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

[abhi-arya1]

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

[cdxker]

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:

• localStorage's behaviour when no or invalid --localstorage-file provided nodejs/node#60303
• Node v25 breaks tests with Web Storage API vitest-dev/vitest#8757

[brianhelba]

Workaround: capricorn86/happy-dom#1950 (comment)

[Dorivika]

Thanks for documenting this! I see this is currently framed as “Mint CLI is incompatible with Node 25” due to the localStorage.getItem is not a function behavior introduced in Node 25’s Web Storage implementation.
Would you be open to a PR that makes the CLI/starter compatible with Node 25 (e.g., by guarding or shimming localStorage usage), rather than treating Node 25 as unsupported? If so, is there a preferred approach or file/area of the codebase you’d like contributors to target?