Memory leak/excessive memory usage during Next.js build in v3.2.1

[tonxxd]

Upgrading @zenstackhq packages from v3.1.1 to v3.2.1 causes a JavaScript heap out of memory error during Next.js production builds. The build process crashes during the optimization phase with FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory.

Environment

• Node.js version: v24.4.0
• Next.js version: 15.5.9
• pnpm version: 10.27.0
• OS: macOS (darwin 25.2.0)
• ZenStack packages affected:
  • @zenstackhq/orm: 3.1.1 → 3.2.1
  • @zenstackhq/plugin-policy: 3.1.1 → 3.2.1
  • @zenstackhq/server: 3.1.1 → 3.2.1
  • @zenstackhq/tanstack-query: 3.1.1 → 3.2.1
  • @zenstackhq/cli: 3.1.1 → 3.2.1

Steps to Reproduce

1. Start with a Next.js 15 project using @zenstackhq packages v3.1.1
2. Update all @zenstackhq packages to v3.2.1
3. Run production build: next build
4. Build crashes during optimization phase with heap out of memory error

Expected Behavior

Build should complete successfully as it does with v3.1.1, using reasonable memory (≤4GB default Node.js heap).

Actual Behavior

Build process crashes after ~2 minutes with:

<--- Last few GCs --->
[39165:0xbee800000]   135344 ms: Mark-Compact 4084.7 (4101.7) -> 4081.0 (4110.0) MB
[39165:0xbee800000]   138846 ms: Mark-Compact (reduce) 4089.1 (4110.0) -> 4083.4 (4097.2) MB

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

Next.js build worker exited with code: null and signal: SIGABRT

Testing Details

We performed systematic testing by updating packages individually:

• ✅ All other dependencies (including @tanstack/react-query, ai, react-hook-form, kysely, pg, etc.) updated successfully without issues
• ✅ Build succeeds with v3.1.1
• ❌ Build fails with v3.2.1
• ✅ Downgrading back to v3.1.1 resolves the issue

Project Context

• Large Next.js 15 application with:
  • 158 files in app/ directory
  • 305 files in components/ directory
  • ZenStack schema generation runs before build
  • Uses React 19, TypeScript, and multiple ZenStack plugins

Workaround

Pin @zenstackhq packages to v3.1.1:

{
  "@zenstackhq/orm": "3.1.1",
  "@zenstackhq/plugin-policy": "3.1.1",
  "@zenstackhq/server": "3.1.1",
  "@zenstackhq/tanstack-query": "3.1.1",
  "@zenstackhq/cli": "3.1.1"
}

[sanny-io]

@tonxxd can you confirm that the issue also happens in the reproduction steps you mentioned? Because I can't reproduce this following those steps.

My memory usage goes from 1.4 GB to 1.9 GB during the build.

[alexbatis]

i'm experiencing the same issue after upgrading to 3.2.1, i have a very similar nextjs app setup.

after upgrading to 3.2.1 and running next build i initially got this error

bun next:build  
$ rm -f ./node_modules/@libsql/hrana-client/LICENSE && SERVICE_NAME=next-app next build --turbo
▲ Next.js 16.1.4 (Turbopack)
- Environments: .env

  Creating an optimized production build ...

> Build error occurred
Error: Turbopack build failed with 2 errors:
./node_modules/@zenstackhq/orm/dist/index.js:570:1
Export v7 doesn't exist in target module
  568 | import { match as match6 } from "ts-pattern";
  569 | import { ulid } from "ulid";
> 570 | import * as uuid from "uuid";
      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  571 |
  572 | // src/client/constants.ts
  573 | var NUMERIC_FIELD_TYPES = [

The export v7 was not found in module [project]/node_modules/uuid/dist/esm-node/index.js [app-route] (ecmascript).
Did you mean to import v5?
All exports of the module are statically known (It doesn't have dynamic exports). So it's known statically that the requested export doesn't exist.

i was able to workaround that error message by adding this to my package.json overrides:

  "overrides": {
    ...
    "uuid": "^11.0.0"
  }

after this i re-ran next build and got an OOM error:

bun next:build
$ rm -f ./node_modules/@libsql/hrana-client/LICENSE && SERVICE_NAME=next-app next build --turbo
▲ Next.js 16.1.4 (Turbopack)
- Environments: .env

  Creating an optimized production build ...
✓ Compiled successfully in 8.0s
  Running TypeScript  ..
<--- Last few GCs --->

[45096:0x84c000000]    50478 ms: Scavenge (interleaved) 4086.1 (4101.2) -> 4082.6 (4101.4) MB, pooled: 0 MB, 3.50 / 0.00 ms  (average mu = 0.304, current mu = 0.266) allocation failure; 
[45096:0x84c000000]    50822 ms: Mark-Compact 4086.4 (4101.7) -> 4080.3 (4101.7) MB, pooled: 0 MB, 341.79 / 0.00 ms  (average mu = 0.246, current mu = 0.181) allocation failure; scavenge might not succeed

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----
...

these are my package versions

    "@zenstackhq/better-auth": "^3.2.1",
    "@zenstackhq/orm": "^3.2.1",
    "@zenstackhq/plugin-policy": "^3.2.1",
    "@zenstackhq/server": "^3.2.1",
    "@zenstackhq/tanstack-query": "^3.2.1",

    "@zenstackhq/cli": "^3.2.1",

after reverting back to these versions

    "@zenstackhq/better-auth": "^3.1.0",
    "@zenstackhq/orm": "^3.1.0",
    "@zenstackhq/plugin-policy": "^3.1.0",
    "@zenstackhq/server": "^3.1.0",
    "@zenstackhq/tanstack-query": "^3.1.0",

    "@zenstackhq/cli": "^3.1.0",

the next build works without any errors

[tonxxd]

@tonxxd can you confirm that the issue also happens in the reproduction steps you mentioned? Because I can't reproduce this following those steps.

My memory usage goes from 1.4 GB to 1.9 GB during the build.

Yes it does for me but maybe is a conflict with some other dependency? again, if i use 3.1 versions with exactly the same other dependencies it works, but 3.2 seems to cause the oom kill.

[sanny-io]

@tonxxd what is the full package.json for the reproduction? I used create-next-app and just accepted all the defaults, but the exact package.json will help us solve this.

[sanny-io]

By the way, this is not an uncommon problem with Next.js in general. If you search for it on Google, there are numerous posts about Next going OOM during builds. It's not necessarily a problem with ZenStack.

If there are no runtime issues, you should be able to just increase the amount of memory with NODE_OPTIONS="--max-old-space-size=8192" until we can figure out what's going on. Please do still post the full package.json when you can.

[sanny-io]

Someone just reported OOM using Nuxt on Discord so it is most likely ZenStack at this point. Before that someone also reported memory issues but that was with 3.2.0

Update: his OOM happens at runtime rather than build time so it might not be related to this...

[ymc9]

Since the OOM happens at build time it's possible that tsc blew up during compilation. What's your typescript version? First thing to check, have you guys tried removing ".next" folder after upgrade and then run build? @tonxxd @alexbatis

It's hard to know what's going wrong without having access to a repro. Are any of your projects shareable?

[alexbatis]

@ymc9 i made a repro here

i made a fork of the v3 branch of better-auth-zenstack-multitenancy -> updated nextjs, updated zenstack deps to ^3.2.1, and re-ran zen generate

the file which ultimately causes the OOM issue is use-api.ts

// OOM build issue happens with schema or schema-lite
// import { schema } from "@/zenstack/schema";
import { schema } from "@/zenstack/schema-lite";
import { useClientQueries } from "@zenstackhq/tanstack-query/react";

// Wrapping useClientQueries in a hook and exporting it causes OOM on build
export const useApi = () => {
  const dbClient = useClientQueries(schema);
  return { api: { db: dbClient } };
};

i have a similar hook in my application (which I unfortunately cannot share) which returns the tanstack query client from useClientQueries along with some other api related code.

to get the OOM issue, you need to run npm run build twice. the first time the build succeeds, the second time the build fails.

if you remove the .next directory the build will succeed, but subsequent builds will fail unless you remove .next first.

though not ideal, the OOM error also goes away when setting "incremental": false, in tsconfig.json

[ymc9]

@ymc9 i made a repro here

i made a fork of the v3 branch of better-auth-zenstack-multitenancy -> updated nextjs, updated zenstack deps to ^3.2.1, and re-ran zen generate

the file which ultimately causes the OOM issue is use-api.ts

// OOM build issue happens with schema or schema-lite
// import { schema } from "@/zenstack/schema";
import { schema } from "@/zenstack/schema-lite";
import { useClientQueries } from "@zenstackhq/tanstack-query/react";

// Wrapping useClientQueries in a hook and exporting it causes OOM on build
export const useApi = () => {
const dbClient = useClientQueries(schema);
return { api: { db: dbClient } };
};
i have a similar hook in my application (which I unfortunately cannot share) which returns the tanstack query client from useClientQueries along with some other api related code.

to get the OOM issue, you need to run npm run build twice. the first time the build succeeds, the second time the build fails.

if you remove the .next directory the build will succeed, but subsequent builds will fail unless you remove .next first.

though not ideal, the OOM error also goes away when setting "incremental": false, in tsconfig.json

Thanks! I'll see what I can find.

[ymc9]

I was able to reproduce the issue. Funny enough you'll have to build the second time to see it ... incremental build is definitely playing a role here.

The main typing changes v3.2 vs v3.1 were the typing for custom procedures, which I checked again and still couldn't understand why it blew up tsc brutally. What's weird is that usually tsc performance issue happens at the checking phase, however, for this repro, it blew up during emit 🥲.

I tried downgrading to typescript 5.4 and it's working again. Also tried Typescript 6 dev and it works too. So apparently some magic happened between the two big black boxes: nextjs's bundler and typescript 5.9.

Without understanding the root cause, my only thoughts to current workaround are:

1. Use NODE_OPTIONS=--max-old-space-size=8192 to increase heap threshold
2. Downgrade or upgrade tsc
3. Disable incremental build in tsconfig

I hope tsc v6 becomes GA soon or a new 5.9.x release can change things.

[ymc9]

Maybe related: vercel/next.js#76704

[alexbatis]

what a weird issue, in the next few days i'll try changing the tsc version in my project next week and see if that helps and report back.

I haven't hit this next.js build issue with any other library in my experience and it works flawlessly with < 3.2 which leads me to believe the culprit is somewhere in the 3.2 release. perhaps some sort of circular reference. reminds me of this issue

i tried NODE_OPTIONS=--max-old-space-size=8192 on the reproduction repo and the build still failed. this time instead of OOM error it gave a type error

NODE_OPTIONS=--max-old-space-size=8192 npm run build

> @better-auth/demo@0.1.0 build
> next build

▲ Next.js 16.1.6 (Turbopack)
- Environments: .env

  Creating an optimized production build ...
✓ Compiled successfully in 5.9s
  Running TypeScript  ..Failed to compile.

./app/admin/page.tsx:397:46
Type error: Parameter 'user' implicitly has an 'any' type.

  395 |                             </TableHeader>
  396 |                             <TableBody>
> 397 |                                 {users?.map((user) => (
      |                                              ^
  398 |                                     <TableRow key={user.id}>
  399 |                                         <TableCell>{user.email}</TableCell>
  400 |                                         <TableCell>{user.name}</TableCell>
Next.js build worker exited with code: 1 and signal: null

which is especially weird considering the LSP picks up the type in my IDE

also somewhat related, i've been keeping an eye on this to follow when tsgo will be supported for next.js builds: vercel/next.js#81472

[ymc9]

what a weird issue, in the next few days i'll try changing the tsc version in my project next week and see if that helps and report back.

I haven't hit this next.js build issue with any other library in my experience and it works flawlessly with < 3.2 which leads me to believe the culprit is somewhere in the 3.2 release. perhaps some sort of circular reference. reminds me of this issue

Apparently if we remove the TypeScript typing for custom procedures introduced in v3.2, the issue goes away, but logically I just don't understand the causality.

[alexbatis]

did some digging and i think i found the fix. i changed this:

export type ProcedureHooks<Schema extends SchemaDef> = Schema extends {
    procedures: Record<string, any>;
} ? {
    /**
     * Custom procedures.
     */
    $procs: ProcedureHookGroup<Schema>;
} : {};

to this:

export type ProcedureHooks<Schema extends SchemaDef> = Schema['procedures'] extends Record<string, any> ? { $procs: ProcedureHookGroup<Schema> } : {};

it has to do with distributive conditional types in typescript. as i understand it:

Schema extends { procedures: ... }

is distributive

Schema['procedures'] extends ...

is not distributive - it checks the indexed property directly

i tested this on my reproduction repo and im consistently able to build the next.js app without errors. i added a few custom procedures and ensured they were typesafe

[ymc9]

did some digging and i think i found the fix. i changed this:

export type ProcedureHooks = Schema extends {
procedures: Record<string, any>;
} ? {
/**
* Custom procedures.
*/
$procs: ProcedureHookGroup;
} : {};
to this:

export type ProcedureHooks = Schema['procedures'] extends Record<string, any> ? { $procs: ProcedureHookGroup } : {};
it has to do with distributive conditional types in typescript. as i understand it:

Schema extends { procedures: ... }
is distributive

Schema['procedures'] extends ...
is not distributive - it checks the indexed property directly

i tested this on my reproduction repo and im consistently able to build the next.js app without errors. i added a few custom procedures and ensured they were typesafe

Awesome, this is great news! Would you like to create a PR? Thanks!