A custom font file added with next/font/local does not load or cannot be found
The build cannot find the font file given in srcShort answer
With next/font/local, src is resolved relative to the file that calls localFont, not the project root. Check that path first. Then use an array of { path, weight, style } for several files, set weight for non-variable fonts, and apply className or variable to an element that wraps the text.
Fix it fast
1Find out which cause you have
Print the folder of the file that calls localFont and compare it with where the font file really is.
grep -rn "localFont" app src --include=*.ts --include=*.tsx2Match what you see, then jump to its fix
- 1
The build cannot resolve the font path, although the file exists in the project.src is relative to the wrong fileFix - 2
Only one weight or style of the family renders.Several font files are passed in the wrong shapeFix - 3
No error at all; text keeps the default font.The font is created but not applied to the elementFix
- 1
What does the error look like?
The build cannot find the font file given in srcThe page shows the fallback font instead of the custom oneOnly one weight of the custom font renders
Cause 1 of 3
src is relative to the wrong file
1Check
src is relative to the directory where the font loader function is called. A path that works from the project root does not work from app/layout.tsx.
grep -rn "src:" app --include=layout.tsx
find . -name "*.woff2" -not -path "./node_modules/*"2Fix
Write the path from the calling file. For a font in app/ next to layout.tsx use './my-font.woff2'. For a font in styles/fonts at the project root, called from app/page.tsx, use '../styles/fonts/my-font.ttf'.
// app/layout.tsx
import localFont from 'next/font/local'
const myFont = localFont({
src: './my-font.woff2',
display: 'swap',
})3Verify
Build the project; the unresolved path message is gone.
npx next buildConfirmed by nextjs.org
Cause 2 of 3
Several font files are passed in the wrong shape
1Check
For several files of one family, src must be an array of objects with a path and, where needed, weight and style. Passing a single string loads only that one file.
grep -rn -A8 "localFont" app --include=*.tsx2Fix
List each file in the array, with its weight and style. Non-variable fonts also need weight; a variable font can use a range such as '100 900'.
const roboto = localFont({
src: [
{ path: './Roboto-Regular.woff2', weight: '400', style: 'normal' },
{ path: './Roboto-Italic.woff2', weight: '400', style: 'italic' },
{ path: './Roboto-Bold.woff2', weight: '700', style: 'normal' },
],
})3Verify
Open the Network tab: each listed file should be requested when text uses its weight.
npm run devConfirmed by nextjs.org
Cause 3 of 3
The font is created but not applied to the element
1Check
localFont only returns the font. Fonts are scoped to the component they are used in, so apply className, style or a CSS variable on an element, and add the font to the Root Layout to cover the whole app.
grep -rn -E "className=\{.*(font|variable)" app --include=layout.tsx2Fix
Put className on the html or body tag, or set the variable option and use var(--name) in your CSS.
const myFont = localFont({ src: './my-font.woff2', variable: '--font-my' })
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" className={myFont.variable}>
<body>{children}</body>
</html>
)
}
/* app/globals.css */
body { font-family: var(--font-my); }3Verify
Read the computed font-family on the body in the browser dev tools.
npm run devConfirmed by nextjs.org
How do I stop it coming back?
- Keep font files next to the file that loads them, so the relative path is short.
- Prefer a variable font file where one exists.
- Define each font once in a fonts file and import the object.
- Apply fonts with className or a CSS variable on the html tag, not per component.
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
AuthUserPoolException: Auth UserPool not configured in a Next.js app
Auth UserPool not configured
The error means an Amplify Auth call ran before Amplify.configure did.
3 causes, each with a fixWeb 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
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fix