These families will not be merged together. The last occurre

Error message

These families will not be merged together. The last occurrence will override previous families for this cssVariable. Review your Astro configuration.

What it means

Companion warning to 'Several font families have been registered for the X cssVariable...': it states the consequence — the families will not be merged, and the last occurrence registered for that cssVariable overrides all previous ones. Fonts from the earlier entries are silently dropped from the generated @font-face set and preloads for them disappear.

Source

Thrown at packages/astro/src/assets/fonts/core/get-or-create-font-family-assets.ts:27

}: {
	fontFamilyAssetsByUniqueKey: FontFamilyAssetsByUniqueKey;
	logger: AstroLogger;
	bold: (input: string) => string;
	family: ResolvedFontFamily;
}) {
	const key = `${family.cssVariable}:${family.name}:${family.provider.name}`;
	let fontAssets = fontFamilyAssetsByUniqueKey.get(key);
	if (!fontAssets) {
		if (
			Array.from(fontFamilyAssetsByUniqueKey.keys()).find((k) =>
				k.startsWith(`${family.cssVariable}:`),
			)
		) {
			logger.warn(
				'assets',
				`Several font families have been registered for the ${bold(family.cssVariable)} cssVariable but they do not share the same name and provider.`,
			);
			logger.warn(
				'assets',
				'These families will not be merged together. The last occurrence will override previous families for this cssVariable. Review your Astro configuration.',
			);
		}
		fontAssets = {
			family,
			fonts: [],
			collectedFontsForMetricsByUniqueKey: new Map(),
			preloads: [],
		};
		fontFamilyAssetsByUniqueKey.set(key, fontAssets);
	}
	return fontAssets;
}

View on GitHub (pinned to 52e6c34790)

Solutions

Make each cssVariable unique per family (or drop the explicit cssVariable for unique defaults)
Ensure entries sharing a variable have identical name and provider so they intentionally merge
Verify the fix in devtools: the CSS variable should resolve to a stack containing every intended family

Defensive patterns

Strategy: validation

Validate before calling

// Assert every emitted cssVariable resolves to exactly one family
const seen = new Map();
for (const f of fonts) {
  if (seen.has(f.cssVariable) && seen.get(f.cssVariable) !== `${f.name}|${f.provider}`) {
    throw new Error(`last-wins override for ${f.cssVariable}`);
  }
  seen.set(f.cssVariable, `${f.name}|${f.provider}`);
}

Prevention

After font config changes, inspect the rendered CSS variable in devtools to confirm every intended family is present
Remember the override direction: the LAST entry for a shared cssVariable wins silently
Keep families that should merge identical in name and provider

When it happens

Trigger: Same as the collision: two or more font config entries share a cssVariable with differing name/provider; the final entry wins and earlier families' files are never emitted.

Common situations: Wondering why only one of two configured families loads in the browser; subtle font regressions after adding a new family that reuses an existing variable.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/5618d61a8a96ae0c. Report an issue: GitHub.