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.

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:
- 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. - Give the build a route out. Export
HTTPS_PROXYandNO_PROXYfor the build step, allowlist both font hosts, and cache.next/cacheso a warm runner does not refetch. - 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 thatnext/fontexists 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.
// 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",
});// 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:
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
| Approach | Network at build | Files served from | Layout-shift control | Best for |
|---|---|---|---|---|
| next/font/google | yes, unless cached | your origin | automatic size-adjust | normal cloud CI |
| next/font/local | no | your origin | automatic size-adjust | air-gapped, Docker, compliance |
| CSS link to fonts.googleapis.com | runtime, by the visitor | none, manual | never, in a production app | |
| Self-hosted @font-face in CSS | no | your origin | manual | teams without next/font |
| next/font/google plus warm cache | first build only | your origin | automatic | repeat CI with cache |
| Symptom | Likely cause | First check |
|---|---|---|
| Failed to fetch, every family | no egress or blocked hosts | curl -I https://fonts.gstatic.com from the runner |
| Failed to fetch, one family only | that family has no requested weight or subset | the Google Fonts specimen page |
Unknown font Intero | misspelled export name | the import list |
| Missing selected subsets | subsets omitted | add subsets: ["latin"] |
| Build passes, text flashes | display not set or fallback removed | display: "swap" and adjustFontFallback |
| Works locally, fails in Docker | build stage has no DNS or proxy | docker build network mode |
| Version detail | Behaviour |
|---|---|
| Next 13.2 and later | subsets is required; missing it is a build error |
| Next 14 | font cache lives under .next/cache; cache it in CI |
| Next 15 and 16 | next/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:
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:
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.orgTest 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:
// 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:
// 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:
NEXT_FONT_GOOGLE_MOCKED_RESPONSES=$PWD/test/font-mocks.js npm run buildKeep 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
@importof the Google Fonts URL insideglobals.css. It compiles and then blocks first paint on a third-party request; it also bypassesnext/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
variablename that collides with a Tailwind theme key. The variable is overridden and the font appears not to apply. - Using
adjustFontFallback: falseto 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 documentationThe Next.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesModule not found: Can't resolve a package or alias in Next.js
TypeScript and the bundler resolve imports separately. Align path aliases, workspace dependencies, exports conditions and filename case.
Tailwind CSS 4: the PostCSS plugin error and the v3 leftovers behind it
The moved PostCSS plugin is only half of it. Match the config extension, drop autoprefixer and postcss-import, and check for a second v3 copy.
Next.js cacheComponents: 'used uncached or runtime data' build error
Cache Components makes the build refuse to guess where the static shell ends. Stream it, cache it with use cache, or declare the route blocking.
Vercel 504: FUNCTION_INVOCATION_TIMEOUT
A serverless invocation has a wall-clock budget. Measure it, stream or defer the work, and raise maxDuration only where it is earned.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.