Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A custom font file added with next/font/local does not load or cannot be found

ErrorThe build cannot find the font file given in src

Short 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.

  • Applies to Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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=*.tsx
  2. 2Match what you see, then jump to its fix

    1. 1The build cannot resolve the font path, although the file exists in the project.src is relative to the wrong fileFix
    2. 2Only one weight or style of the family renders.Several font files are passed in the wrong shapeFix
    3. 3No error at all; text keeps the default font.The font is created but not applied to the elementFix

What does the error look like?

  • The build cannot find the font file given in src
  • The page shows the fallback font instead of the custom one
  • Only 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 build

Confirmed by nextjs.org

Did this fix it?

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=*.tsx

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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.tsx

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.