@next/font/local failed to run or is incorrectly configured.

Error message

@next/font/local failed to run or is incorrectly configured.

Read more: https://nextjs.org/docs/app/building-your-application/optimizing/fonts

What it means

`@next/font/local`'s shim throw: after the version check passes, the file unconditionally throws because the real implementation lives inside `next`. Hitting this means the standalone `@next/font/local` package executed instead of being aliased to Next's internal implementation. As with the google variant, the message directs users to the font docs and (in dev) suggests restarting `next dev` after install.

Source

Thrown at packages/font/local/index.js:15

// Validate next version
const semver = require('next/dist/compiled/semver')
if (semver.lt(require('next/package.json').version, '13.0.0')) {
  throw new Error('`@next/font` is only available in Next.js 13 and newer.')
}

let message = '@next/font/local failed to run or is incorrectly configured.'
if (process.env.NODE_ENV === 'development') {
  message +=
    '\nIf you just installed `@next/font`, please try restarting `next dev` and resaving your file.'
}

message += `\n\nRead more: https://nextjs.org/docs/app/building-your-application/optimizing/fonts`

throw new Error(message)

View on GitHub (pinned to 0ae8c72462)

Solutions

Import from the built-in `next/font/local` instead of `@next/font/local`.
Restart `next dev` after installing/updating (the dev hint calls this out).
Clear `node_modules` and lockfile and reinstall to fix resolution.
Ensure no local folder/alias named `@next/font` shadows the package.

Example fix

// before
import localFont from '@next/font/local'

// after
import localFont from 'next/font/local'
const myFont = localFont({ src: './my-font.woff2' })

Defensive patterns

Strategy: fallback

Validate before calling

// Prefer the built-in; detect it before relying on @next/font/local.
try {
  require.resolve('next/font/local')
} catch {
  throw new Error('next/font/local not found; install Next 13.2+')
}

Type guard

function hasBuiltInLocalFont(): boolean {
  try { require.resolve('next/font/local'); return true } catch { return false }
}

Prevention

Import from next/font/local, not @next/font/local.
Restart next dev after installing/updating.
Reinstall node_modules to clear stale shims.

When it happens

Trigger: Importing `@next/font/local` where the npm-published shim runs (rather than Next's internal `next/font/local`), e.g. wrong resolution, stale cache, or a bundler not applying Next's alias.

Common situations: Standalone `@next/font` install that the build failed to alias; stale node_modules after a Next upgrade; conflicting local package shadowing Next's internal one.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/437bc29216897eba. Report an issue: GitHub.