Next.js says Module parse failed: you may need an appropriate loader
Module parse failed: Unexpected tokenShort answer
The bundler found a file it cannot read as JavaScript. Either you import a non-code file (svg, pdf, txt) with no loader for it, or a package in node_modules ships raw TypeScript or JSX that Next.js does not compile. Add a loader rule for the file type, or list the package in transpilePackages.
Fix it fast
1Find out which cause you have
Read the first line of the error. It names the file the bundler could not parse. A path ending in .svg, .pdf or .txt points to cause 1 or 2. A path inside node_modules points to cause 3.
npx next build 2>&1 | grep -B2 -A8 "Module parse failed"2Match what you see, then jump to its fix
- 1
The failing path ends in .svg, .pdf, .txt or another data format.A non-JavaScript file is imported and no loader is set (Turbopack)Fix - 2
The same import fails only under webpack, for example when next dev or next build is started with the webpack bundler.The build uses webpack and has no rule for the file typeFix - 3
The failing path is inside node_modules and the line shown is TypeScript or JSX, for example a type annotation.A package in node_modules ships TypeScript, JSX or other sourceFix
- 1
What does the error look like?
Module parse failed: Unexpected tokenYou may need an appropriate loader to handle this file type
Cause 1 of 3
A non-JavaScript file is imported and no loader is set (Turbopack)
1Check
Find the import. Turbopack handles CSS and JavaScript on its own, but any other file type needs a rule in next.config.
grep -rnE "import .* from '.*\.(svg|pdf|txt)'" app src components 2>/dev/null2Fix
To import a file as a URL, give its extension the asset type. To turn SVG files into React components, add the @svgr/webpack loader. Loaders must return JavaScript, and rules run in order.
// next.config.js
module.exports = {
turbopack: {
rules: {
'*.pdf': { type: 'asset' },
'*.svg': { loaders: ['@svgr/webpack'], as: '*.js' },
},
},
}3Verify
Restart the dev server, then build.
npx next buildConfirmed by nextjs.org
Cause 2 of 3
The build uses webpack and has no rule for the file type
1Check
Custom webpack settings live in the webpack function of next.config. Check whether one exists and whether it covers the extension.
grep -n "webpack" next.config.*2Fix
Add a rule for the extension inside the webpack function and return the changed config. Install the loader first.
// next.config.js
module.exports = {
webpack: (config) => {
config.module.rules.push({
test: /\.svg$/,
use: ['@svgr/webpack'],
})
return config
},
}3Verify
Run the build with the same bundler that failed.
npx next buildConfirmed by nextjs.org
Cause 3 of 3
A package in node_modules ships TypeScript, JSX or other source
1Check
Next.js does not compile code inside node_modules unless you ask it to. Open the failing file and the package's package.json main and exports fields.
cat node_modules/PACKAGE/package.json | grep -E '"(main|module|exports|types)"'
head -20 node_modules/PACKAGE/path/from/the/error.ts2Fix
List the package by name in transpilePackages. Paths and globs are not accepted. A package cannot be in both transpilePackages and serverExternalPackages.
// next.config.js
module.exports = {
transpilePackages: ['package-name', '@scope/pkg'],
}3Verify
Rebuild. The error for that package is gone.
npx next buildConfirmed by nextjs.org
How do I stop it coming back?
- Prefer packages that publish compiled JavaScript with a types file.
- Keep loader rules in next.config next to a comment saying which import needs them.
- Put plain downloads such as PDFs in public and link them by URL instead of importing them.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix