Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

next/font: Failed to fetch a Google font during the build

The font is fetched during the build, not at runtime. Vendor it with next/font/local or give CI and Docker a route out.

~6 min readNext.js
#Next.js#next/font#CI#Docker
A build cube with a letter glyph crate and a broken cyan download arrow beside a blocked cloud plate

Introduction & Quick Summary

next build fails with Failed to fetch Inter from Google Fonts. and a link to the failed-to-fetch-google-font message page. Nothing about the component changed, the font worked in local development, and the failure appears only in CI, in a Docker build or on a machine without direct internet access.

That is the mechanism: next/font/google is not a runtime request. Next.js downloads the CSS and the WOFF2 files from fonts.googleapis.com and fonts.gstatic.com while building, writes them into .next, and serves them from your own origin afterwards. A build environment that cannot reach those hosts - an air-gapped runner, a Docker build without egress, a corporate proxy that only allowlists the npm registry, or a network where Google Fonts is blocked - has no way to complete it.

Three fixes, in order of how much control they give you:

  1. Vendor the font. Download the WOFF2 files once and use next/font/local. The build then needs no network at all, which is the only option that is stable in every environment.
  2. Give the build a route out. Export HTTPS_PROXY and NO_PROXY for the build step, allowlist both font hosts, and cache .next/cache so a warm runner does not refetch.
  3. Do not silently fall back to a <link> tag. Moving the font to a stylesheet import trades a build error for a render-blocking third-party request and a privacy question, and it undoes the layout-shift protection that next/font exists to provide.

The rest covers what the loader actually does, how to tell a network failure from a wrong font name or a bad subsets argument, and the version details that decide whether a retry, a cache or a vendored file is the right answer.

Core Mechanics, Signatures & Reproducible Setup

next/font/google runs a loader at build time. For each call it requests the Google Fonts CSS API for the requested family, weights and subsets, rewrites the returned CSS to point at local files, downloads each WOFF2, emits them into the build output, and generates a class with a computed size-adjust fallback so text does not jump when the real font arrives. The download happens per build, unless it is served from the font cache inside .next/cache.

tsx
// app/fonts.ts import { Inter, JetBrains_Mono } from "next/font/google"; export const sans = Inter({ subsets: ["latin"], display: "swap", variable: "--font-sans", weight: ["400", "500", "700"], }); export const mono = JetBrains_Mono({ subsets: ["latin"], display: "swap", variable: "--font-mono", });
tsx
// app/layout.tsx import { sans, mono } from "./fonts"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en" className={`${sans.variable} ${mono.variable}`}> <body className="font-sans">{children}</body> </html> ); }

The dev server caches per run and is forgiving: a transient failure is retried on the next request. Production is less forgiving, because next build fails the whole compilation when the loader throws. Reproduce the CI failure locally without touching your network by pointing the loader at a dead proxy:

bash
HTTPS_PROXY=http://127.0.0.1:9 npx next build # Failed to fetch `Inter` from Google Fonts.

The same build with a reachable network succeeds, which isolates the cause in one command. Next.js also honours NEXT_FONT_GOOGLE_MOCKED_RESPONSES for tests, which maps requested URLs to canned CSS files so unit and e2e builds never touch the network.

Key Comparison Table

ApproachNetwork at buildFiles served fromLayout-shift controlBest for
next/font/googleyes, unless cachedyour originautomatic size-adjustnormal cloud CI
next/font/localnoyour originautomatic size-adjustair-gapped, Docker, compliance
CSS link to fonts.googleapis.comruntime, by the visitorGooglenone, manualnever, in a production app
Self-hosted @font-face in CSSnoyour originmanualteams without next/font
next/font/google plus warm cachefirst build onlyyour originautomaticrepeat CI with cache
SymptomLikely causeFirst check
Failed to fetch, every familyno egress or blocked hostscurl -I https://fonts.gstatic.com from the runner
Failed to fetch, one family onlythat family has no requested weight or subsetthe Google Fonts specimen page
Unknown font Interomisspelled export namethe import list
Missing selected subsetssubsets omittedadd subsets: ["latin"]
Build passes, text flashesdisplay not set or fallback removeddisplay: "swap" and adjustFontFallback
Works locally, fails in Dockerbuild stage has no DNS or proxydocker build network mode
Version detailBehaviour
Next 13.2 and latersubsets is required; missing it is a build error
Next 14font cache lives under .next/cache; cache it in CI
Next 15 and 16next/font is built in, no separate package, Turbopack uses the same loader
Any version--turbo does not change build-time network requirements

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Vendor the font and remove the network from the build

This is the durable fix. Download the WOFF2 files from the Google Fonts CSS response for the exact weights and subsets you need, commit them under app/fonts/, and call next/font/local:

tsx
import localFont from "next/font/local"; export const sans = localFont({ src: [ { path: "./fonts/inter-400.woff2", weight: "400", style: "normal" }, { path: "./fonts/inter-700.woff2", weight: "700", style: "normal" }, ], display: "swap", variable: "--font-sans", fallback: ["system-ui", "Segoe UI", "sans-serif"], });

src paths are relative to the file that calls localFont, and the files must be inside the project so the bundler can emit a content-hashed URL. Variables are still available for Tailwind or any CSS that reads var(--font-sans).

2. Give CI and Docker a route to the font hosts

When vendoring is not possible yet, make the build environment explicit. In Docker, the build stage needs egress or a proxy passed as build arguments, and the proxy must be set for the build, not only for the final image:

dockerfile
FROM node:22-alpine AS build WORKDIR /app ARG HTTPS_PROXY ARG NO_PROXY ENV HTTPS_PROXY=$HTTPS_PROXY NO_PROXY=$NO_PROXY COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build
# CI step, keeping the cache warm between runs - uses: actions/cache@v4 with: path: .next/cache key: next-font-${{ hashFiles('app/fonts.ts') }} - run: npm run build env: HTTPS_PROXY: ${{ secrets.BUILD_PROXY }} NO_PROXY: localhost,127.0.0.1,registry.npmjs.org

Test reachability from the runner before the build, so a proxy misconfiguration shows as a network error rather than a font error. The HTTP header inspector shows the status and headers of the Google Fonts CSS endpoint from wherever you run it, which is enough to tell a blocked host from a slow one.

3. Tell a policy failure from a name or subset failure

The loader throws the same top-level message for several problems, so read the cause line above it. A wrong family or an unavailable weight produces a 400 from the CSS API and the same text; a missing subset errors before any request:

tsx
// wrong: Inter has no 300 weight in variable form on the static endpoint export const sans = Inter({ subsets: ["latin"], weight: ["300", "400"] }); // right: request only weights the family provides, or omit weight for variable fonts export const sans = Inter({ subsets: ["latin"] });

For variable families, omitting weight fetches the full axis and is usually smaller than listing several weights, because one file covers all of them.

4. Monorepos, multiple roots and duplicated downloads

Each next/font call is a separate loader invocation. A monorepo where three apps request Inter with different subsets pays three times. Share one module per app and keep the arguments identical so a shared build cache can hit:

ts
// packages/ui/src/fonts.ts - one definition, imported by every app export const fontArgs = { subsets: ["latin"], display: "swap" } as const;

If a build runs on every pull request with no cache, an unreachable host costs the whole job. Set a build timeout and treat the font step as a dependency of the build, not as an optional asset.

5. Fonts in tests and e2e runs

Component tests and Playwright runs should never fetch fonts. Point the loader at mocked responses and make the test environment deterministic:

bash
NEXT_FONT_GOOGLE_MOCKED_RESPONSES=$PWD/test/font-mocks.js npm run build

Keep that file in the repo with a comment explaining which URLs it maps, because it is the one piece of test setup that silently rots when font arguments change.

Common Compilation/Runtime Mistakes & Version Gotchas

  • A CSS @import of the Google Fonts URL inside globals.css. It compiles and then blocks first paint on a third-party request; it also bypasses next/font's metrics.
  • Forgetting subsets. Since Next 13.2 this is an error, not a warning, and the message names the font rather than the missing argument.
  • Assuming a warm npm cache helps. The font cache lives in .next/cache, not in ~/.npm; cache the former.
  • Setting the proxy only for npm ci. The build is a separate process with its own environment.
  • A variable name that collides with a Tailwind theme key. The variable is overridden and the font appears not to apply.
  • Using adjustFontFallback: false to fix a visual diff. It disables the metric override and brings back the layout shift.
  • Pinning a Google Fonts family name with spaces. Use the exported identifier (JetBrains_Mono) rather than the display name inside the options object.
  • Building an output: "export" site offline. Static export does not remove the build-time fetch.

Primary references: the next/font API reference documents the loader arguments, caching and the local-font escape hatch, and the same page's section on local fonts covers next/font/local with relative src paths.

Official references

primary documentation

The Next.js documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Next.js guides

More in Next.js

All Next.js guides

The guides filed next to this one in Next.js, in library order.