RangeError: Map maximum size exceeded with createMessagesDeclaration on large message files (~2,500+ keys)

[arolariu]

Encountering RangeError: Map maximum size exceeded out of the blue.

Description

I have some large messages files (~218KB, ~2,554 leaf keys, max nesting depth 6) in my project. Whenever I do next build, the build fails due to the typescript server running out of memory for type checking -- I presume that my current setup (with very large, nested messages AND lots of useTranslations() calls) makes the typescript server crash.

Here's the exact crash that it encounteres during type checking:

RangeError: Map maximum size exceeded
    at Map.set (<anonymous>)
    at getStringLiteralType (tsc.js:62989:65)
    at getTemplateLiteralType (tsc.js:61982:14)

The typescript compilation itself succeeds (✓ Compiled successfully in 41s, for example), but the subsequent TypeScript type-check phase hits the V8 Map entry limit (2^24 = 16,777,216 entries).

I've tried to use the --max-old-space-size flag, but it does NOT help as this is an entry count limit, not a memory issue.

Environment

• next-intl: 4.8.3
• Next.js: 16.2.1
• TypeScript: 5.9.3
• Node.js: 24.x
• OS: Windows 11 / Ubuntu (GitHub Actions)

Reproduction Steps

1. Create a Next.js App Router project with next-intl v4
2. Create a messages/en.json with ~2,500+ leaf keys at max depth 6 (see metrics below)
3. Have ~170 useTranslations() call sites across the project
4. Run next build

Expected: Build succeeds with type-checking
Actual: RangeError: Map maximum size exceeded during type-check phase

Message File Metrics

Metric	Value
File size	218.5 KB
Total leaf keys	2,554
Total namespaces	851
Max nesting depth	6
Top-level namespaces	14
Locales	3 (en, ro, fr)
useTranslations() call sites	~170

Root Cause Analysis

The generated .d.json.ts creates a type representing all ~2,554 dot-separated key paths as a string literal union. When useTranslations("SomeNamespace") is called, TypeScript's recursiveTypeRelatedTo compares each namespace path against the full union. With ~170 call sites × ~2,554 key paths, the combinatorial type comparisons exceed V8's Map limit of 16,777,216 entries.

This is fundamentally the same issue as:

• microsoft/TypeScript#55630
• i18next/i18next#2001 (fixed by simplifying type definitions)

(^-- above paragraphs have been written by Claude Opus 4.6 1M context)

Current Workaround

Setting typescript.ignoreBuildErrors: true in next.config.ts and relying on separate CI type-checking.

Minimal Reproduction

WIP.

[arolariu]

Hi,

I've used AI (GHCP with Claude 4.6) to draft this issue, but to be clear: I've ran into this weird scenario, where, given a very big messages file, strict tsconfig.json, AND type declarations, the nextjs typescript checker step crashes with Map maximum size exceeded error.

---

I'm currently trying to create an easy reproduction, but the issue happens for my personal project over at https://github.com/arolariu/arolariu.ro/tree/main/sites/arolariu.ro <-- this should be buildable out of the box, but I understand that it is not an isolated sandbox to experiment and observe the issue.

I'm working on creating such environment.

---

After further research, this seems like a problem in the type graph and its resolution, not specifically for next-intl to handle / tackle.

I'd still ask -- from next-intl perspective, are there any guidelines for this exact scenario? Claude is telling me that next-intl creates a lot of work for the type checker due to the complex type declaration union generation.

[arolariu]

(TL;DR: looks like the next-intl type generator does a cartesian product of all parents x children keys, crashing the TS server?)

I've dedicated some more time on this with Claude Opus 4.6 1M context, and here's what it found:

1. The Symptom

Running npm run build:website (which invokes next build, which invokes the
TypeScript type checker) crashes with:

RangeError: Map maximum size exceeded
    at Map.set (<anonymous>)
    at getStringLiteralType (_tsc.js:62989)
    at getTemplateLiteralType (_tsc.js:61982)
    at mapType (_tsc.js:69915)               ← iterating a union
    at getTemplateLiteralType (_tsc.js:61970) ← recursive call
    at computeBaseConstraint (_tsc.js:58897)  ← resolving a generic constraint

The crash persists even with --max-old-space-size=8192 (8 GB heap), confirming
it is not an out-of-memory error. It is a hard V8 platform limit on the number
of entries a Map can hold.

---

2. Measuring the V8 Map Limit

Reproduction:

// measure-map-limit.js
const map = new Map();
let i = 0;
try {
  while (true) { map.set('k' + i, i); i++; }
} catch (e) {
  console.log(`Map limit: ${i} entries (${(i/1e6).toFixed(2)}M)`);
  console.log(`Error: ${e.message}`);
}

Result (Node.js 24.5.0, V8 12.x, Windows x64):

Map limit: 8388608 entries (8.39M)
Error: Map maximum size exceeded

The V8 Map limit on this platform is 8,388,608 entries (exactly 2^23).

---

3. Identifying the Map That Overflows

TypeScript's type checker maintains an internal cache called stringLiteralTypes:

// TypeScript compiler source (_tsc.js)
var stringLiteralTypes = new Map();

function getStringLiteralType(value) {
    let type;
    return stringLiteralTypes.get(value)
      || (stringLiteralTypes.set(value, type = createLiteralType(128, value)), type);
}

Every unique string literal type encountered during compilation is stored here.
When the Map reaches 8,388,608 entries, the next .set() call throws RangeError.

---

4. Instrumenting the Crash Point

We patched getStringLiteralType to catch the overflow and dump the Map contents:

function getStringLiteralType(value) {
    let type;
    let existing = stringLiteralTypes.get(value);
    if (existing) return existing;
    type = createLiteralType(128, value);
    try {
      stringLiteralTypes.set(value, type);
    } catch (e) {
      console.error("MAP OVERFLOW at size=" + stringLiteralTypes.size);
      console.error("Crashing value=" + JSON.stringify(value.substring(0, 200)));
      // ... dump key distribution and samples ...
      throw e;
    }
    return type;
}

Result:

MAP OVERFLOW at size=8388608
Crashing value="Acknowledgements.stats.development.serviceProviderTerms.content"
Key distribution: short(<20)=36732  mid(20-100)=8126085  long(>100)=225791

Category	Count	% of Map	Description
Short (<20 chars)	36,732	0.4%	Normal: property names, HTML tags, enum values
Mid (20-100 chars)	8,126,085	96.9%	Bogus cross-branch path concatenations
Long (>100 chars)	225,791	2.7%	Deep cross-branch concatenations

96.9% of the 8.39M entries are strings that do not correspond to any valid
translation key. They are junk produced by a cartesian-product expansion.

---

5. The Bogus Strings — Cross-Branch Concatenations

Samples from the Map's long-key region:

"Acknowledgements.stats.development.EditInvoice.analyzeDialog.options.invoiceOnly.features.paymentMethodDetection"
"Acknowledgements.stats.development.CreateInvoice.detailsForm.fields.paymentType.options.mobilePayment"
"Invoices.Shared.notifications.timeAgo.ViewInvoice.receiptScanCard.controls.zoomOut"
"About.Platform.techStack.technologies.playwright.ViewScans.scanCard.deleteDialog"

Each of these glues a path from one subtree to a path from a completely different
subtree:

"Acknowledgements.stats.development"  ←  from Acknowledgements branch
       +  "."  +
"EditInvoice.analyzeDialog.options.invoiceOnly.features.paymentMethodDetection"  ←  from Invoices branch

These are NOT valid keys in en.json. They are artifacts of a cartesian-product
computation inside TypeScript's template literal type resolver.

---

6. How the Cartesian Product Happens

6.1 The Type Chain

The project's i18n type augmentation (src/app/globals.ts):

import en from "../../messages/en.json";

declare module "next-intl" {
  interface AppConfig {
    Messages: typeof en;    // ← Feeds the 2,810-key JSON into next-intl's type system
  }
}

next-intl's useTranslations function signature (node_modules/use-intl):

function useTranslations<
  NestedKey extends NamespaceKeys<Messages, NestedKeyOf<Messages>> = never
>(namespace?: NestedKey): ...

next-intl's recursive key type (node_modules/use-intl/dist/types/core/MessageKeys.d.ts):

export type NestedKeyOf<ObjectType> = ObjectType extends object ? {
    [Property in keyof ObjectType]:
      `${Property & string}` | `${Property & string}.${NestedKeyOf<ObjectType[Property]>}`;
}[keyof ObjectType] : never;

6.2 What NestedKeyOf<typeof en> Should Produce

For the actual en.json structure (14 top-level keys, 7 levels deep, 2,810 leaves):

NestedKeyOf<typeof en> =
  | "Common"
  | "Common.accessibility"
  | "Common.accessibility.logoAlt"
  | "Common.accessibility.toggleTheme"
  | "Navigation"
  | "Navigation.links"
  | ...
  | "Invoices.ViewInvoice.receiptScanCard.controls.toggleZoom"
  | ...   (3,729 total members — all valid dot-notation paths)

This 3,729-member union is the correct result. If TypeScript stopped here,
there would be no problem.

6.3 Where It Goes Wrong: computeBaseConstraint

When TypeScript encounters useTranslations("Invoices.ViewInvoice"), it must verify
that "Invoices.ViewInvoice" satisfies the constraint:

NestedKey extends NamespaceKeys<Messages, NestedKeyOf<Messages>>

To do this, TypeScript calls computeBaseConstraint on the constraint type. This
function must resolve NamespaceKeys<...> into a concrete union. As part of this
resolution, it encounters the template literal type:

`${Property & string}.${NestedKeyOf<ObjectType[Property]>}`

The getTemplateLiteralType function processes this template. The template has two
type slots:

• Slot 0: Property & string — a union of property names (e.g., "Common" | "Navigation" | ...)
• Slot 1: NestedKeyOf<ObjectType[Property]> — the recursive nested keys

The bug: During computeBaseConstraint, TypeScript resolves NestedKeyOf<ObjectType[Property]>
to its base constraint. Because Property is a type parameter being iterated,
TypeScript doesn't narrow ObjectType[Property] to the specific property — it uses
the full NestedKeyOf<Messages> result (3,729 members) as the constraint for
the inner slot.

This turns the template literal into:

`${PropertyUnion}.${FullNestedKeyOfUnion}`
 = `${"Common" | "Navigation" | ... (14 members)}.${all 3,729 paths}`

getTemplateLiteralType expands this via mapType:

For each of 14 properties P:
  For each of 3,729 paths X:
    Create string literal type:  P + "." + X

= 14 × 3,729 = 52,206 string literals at the first recursive level.

6.4 The Recursion Multiplies It Further

But NestedKeyOf is recursive. The same expansion happens at every level of the
JSON tree. At each level, the intermediate object nodes become new Property values,
and the inner NestedKeyOf is again expanded to the full 3,729-member union:

Level	Intermediate Nodes at Level	× Full Union (3,729)	= String Literals Created
1	14 (top-level keys)	× 3,729	= 52,206
2	84 (level-2 objects)	× 3,729	= 313,236
3	346 (level-3 objects)	× 3,729	= 1,290,234
4	1,118 (level-4 objects)	× 3,729	= 4,169,022
5	1,568 (level-5 objects)	× 3,729	= 5,846,272
6	528 (level-6 objects)	× 3,729	= 1,968,912
7	71 (level-7 objects)	× 3,729	= 264,759
Total	3,729		≈ 13,904,641

Plus the 36,732 normal (non-template-literal) string types from the rest of the
compilation:

Total entries attempted: ~13,941,373

The Map overflows at 8,388,608 — somewhere during Level 4/5 processing.

This matches our observed data:

• Map at crash: 8,388,608 entries
• 96.9% are mid-length cross-branch concatenations (the cartesian products)
• Sample keys confirm cross-branch patterns (Acknowledgements + EditInvoice)

---

7. Empirical Confirmation

Test	Action	Result
Baseline	tsc --noEmit with Messages: typeof en	CRASH — Map overflow at 8,388,608
With 8GB heap	tsc --noEmit --max-old-space-size=8192	CRASH — same error (not OOM)
Without Messages	Comment out Messages: typeof en, run tsc --noEmit	SUCCESS — completes in 33.5s
V8 Map limit	Measured with test script	8,388,608 entries (2^23)
Map contents	Instrumented getStringLiteralType catch block	96.9% bogus cross-branch strings

---

8. Why checkCrossProductUnion Doesn't Prevent This

TypeScript has a safeguard in getTemplateLiteralType:

function checkCrossProductUnion(types) {
    const size = getCrossProductUnionSize(types);
    if (size >= 1e5) {   // 100,000 threshold
      error(currentNode, "Expression produces a union type that is too complex");
      return false;
    }
    return true;
}

This guard caps cross products at 100,000. However:

• It only fires when getTemplateLiteralType is called from a direct expression
• When called from computeBaseConstraint → getTemplateLiteralType, the guard
  checks the IMMEDIATE cross product (e.g., 14 × 3,729 = 52,206 < 100,000), which passes
• The recursive accumulation across all 7 levels is NOT checked as a whole
• Each individual level passes the 100K check, but the TOTAL across all levels is ~14M

---

9. Solution

Recommended: Namespace-Scoped Type Augmentation

// src/app/globals.ts
import type en from "../../messages/en.json";

const locales = ["en", "ro", "fr"] as const;

type TopLevelMessages = {
  [K in keyof typeof en]: Record<string, unknown>;
};

declare module "next-intl" {
  interface AppConfig {
    Locale: (typeof locales)[number];
    Messages: TopLevelMessages;
  }
}

Why this works: NestedKeyOf<TopLevelMessages> generates only 14 string literals
(the top-level keys). Record<string, unknown> has no enumerable keys for recursion.
The cartesian product becomes 14 × 0 = 0 cross-branch strings.

What you keep: Namespace validation (useTranslations("Invoices") type-checked)
What you lose: Deep key autocomplete (acceptable — runtime validation still works)

Implementation Steps

1. Modify src/app/globals.ts — replace Messages: typeof en with Messages: TopLevelMessages
2. Set ignoreBuildErrors: false in next.config.ts:180
3. Run tsc --noEmit — verify no crash
4. Run npm run build:website — verify full build
5. Run npm run test:website — verify tests pass

[cleitonixc]

Hitting a related symptom on a similarly sized message tree — same createMessagesDeclaration codepath, but the failure mode is the NamespaceKeys instantiation cap rather than the V8 Map ceiling.

Environment

• next-intl: 4.8.x
• Next.js: 16.x (App Router)
• TypeScript: 5.9.x
• Locales: 5 (en-US, pt-BR, es-ES, fr-FR, de-DE)
• Per-locale message file: ~396 KB, 6,832 leaf keys
• Total useTranslations() call sites: ~600+ across the monorepo

Symptom

Adding new keys at marketing.cookieConsent.{banner,modal,categories}.* made useTranslations("marketing.cookieConsent") raise:

Argument of type '"marketing.cookieConsent"' is not assignable to parameter of type 'NestedKeyOf<...> | "<huge union of namespace paths>"'.
  Type '"marketing.cookieConsent"' is not assignable to type
  '"common.X" | "common.Y" | ... and 21305 more'.

The truncated "21305 more" is the giveaway — the NamespaceKeys distributive union appears to be capped at exactly 21,305 entries before TypeScript bails out, so newly added paths beyond that point are silently undiscoverable as namespaces. The leaf access (t("banner.title")) would still typecheck if the namespace were valid, but the namespace itself is what's truncated.

Workaround we shipped

Use a shallower namespace and flatten the access:

// Before (errored — namespace not in the truncated union)
const t = useTranslations("marketing.cookieConsent");
t("banner.title");

// After (works — "marketing" is shallow enough to remain in the union)
const t = useTranslations("marketing");
t("cookieConsent.banner.title");

This is awkward because the workaround "depth" depends on where in the alphabetical/serialization order your new namespace lands in the generated union — there's no deterministic way for a consumer to know which paths are within the cap.

Suggested fix direction

The user-facing cap is the same root cause as #2296 (combinatorial explosion in the generated .d.json.ts namespace union). Whatever solution lands for #2296 — collapsing the union, lazy generation per call site, or string fallback past a threshold — should also address this case. Filing as a related data point rather than a separate issue.

Happy to provide a redacted minimal repro if useful.

— Reporter is downstream consumer at @parisgroup-ai/cursos (private repo).

[amannn]

Thanks for opening this issue and the careful analysis!

It's correct that there's unfortunately an upper limit with what createMessagesDeclaration can handle. Have you by chance tried the TypeScript 7.0 beta to see if it brings improvements here?

Otherwise, as you mention above, you can currently work around this issue by simplifying the checking—e.g. only validating namespaces:

// src/app/globals.ts
import type en from "../../messages/en.json";

type TopLevelMessages = {
  [K in keyof typeof en]: Record<string, unknown>;
};

declare module "next-intl" {
  interface AppConfig {
    Messages: TopLevelMessages;
  }
}

From a different angle, there's also an option to use static analysis to validate that you're reading valid messages—next-intl might offer more in this direction in the future.

I guess it's a bit debatable if the type augmentation will remain helpful for autocompleting message keys in the foreseeable future, with agents producing more and more code. Maybe if verification is handled by a separate lint task that relies on static analysis of useTranslations calls, this could be sufficient. I hope that the performance improvements of the TypeScript Go rewrite will buy as a bit of time here to evaluate this.

Other than that, the more recently shipped useExtracted doesn't suffer from this issue in the first place—a nice benefit for developers who like this kind of API.

[ihardlight]

Hello @arolariu,

I am currently working on two improvements to next-intl:

1. Adding performance tests for typescript feat: add perf tests #2311
2. Rewriting NestedValuesOf and MessageKeys fix: type checking for union message types #2290

These changes may resolve your issue after merge and release. However, I am unable to guarantee this. If you can test these changes on your project it will expedite the resolution of the reported bug.

[amannn]

@blessanm86 also implemented an idea here: #2314 (comment)

[brianguertin]

@amannn I wouldn't blame TS compiler if the library is asking for millions/billions of types to be defined. But maybe the approach just needs to be a linter as you said.

For the record, I tried tsgo which, instead of crashing due to map size, just eats RAM until it's process gets killed.

This is on PC with 64GB RAM. It will use all 64GB then crash. My messages file is ~10k lines.

Perhaps tsgo did remove the map limit, so it happily tries to load a bazillion entries 😅