Repository navigation
node 25 TypeError: localStorage.getItem is not a function #116
Description
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
Activity
chronark commentedon Nov 5, 2025
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 locationdocker run --rm -it \ -p 3000:3000 \ -v "$(pwd):/project" \ -w /project/apps/docs \ node:24 \ npx --yes mint@latest devmmichie commentedon Nov 6, 2025
Hit this bug, while evaluating mintlify. Not a good start for me.
dweekly commentedon Nov 9, 2025
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-filewas 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 commentedon Nov 10, 2025
++ Getting the same issue with the same versions for our monorepo
cdxker commentedon Nov 10, 2025
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/fnmor 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-fileprovided nodejs/node#60303brianhelba commentedon Nov 12, 2025
Workaround: capricorn86/happy-dom#1950 (comment)
Dorivika commentedon May 5, 2026
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?
awoods187 commentedon Jun 3, 2026
Is there any plan to address this limitation?