“type instantiation is excessively deep” when importing api – growing backend makes compiler blow up
Hi Convex team & community,
We’re hitting a persistent TS2589 error and would like a sanity-check + maybe turn this into a feature request.
1. Context
Stack: Next 15.3, React 19, TypeScript 5.8.2, Convex 1.24.8
Backend: ~65 Convex functions (and growing)
Typical page code
import { api } from "@/convex/_generated/api";
const people = useQuery(api.entities.getPeopleWithFilters, args);
2. Problem
As soon as a page imports api the compiler tries to resolve the full union type of every function.
With our current backend size that exceeds the recursion limit and TS throws:
error TS2589: Type instantiation is excessively deep and possibly infinite
It happens before any cast we add to the function or return value can help.
Work-around we landed on:
// eslint-disable-next-line @typescript-eslint/no-var-requires
const api: any = require("@/convex/_generated/api").api;
This is local to the one page that fails; other files keep full typing.
4 Questions
1. Is the “expand entire api union on property access” behaviour expected?
2. Is there a lighter-weight import pattern we missed (e.g., per-function exports)?
3. Would the team consider generating a “light client” type or splitting the api type so large projects don’t blow TS’s recursion budget?
4. Happy to provide a minimal repro if needed.
Thanks for the awesome product and for any guidance!
Yuriy
4 Replies
Thanks for posting in <#1088161997662724167>.
Reminder: If you have a Convex Pro account, use the Convex Dashboard to file support tickets.
- Provide context: What are you trying to achieve, what is the end-user interaction, what are you seeing? (full error message, command output, etc.)
- Use search.convex.dev to search Docs, Stack, and Discord all at once.
- Additionally, you can post your questions in the Convex Community's <#1228095053885476985> channel to receive a response from AI.
- Avoid tagging staff unless specifically instructed.
Thank you!
There are quite a few posts about this if you search, its usually related to some other issue rather than a ts limit.
It can be a simple not defining return types back to certain actions.
Like i'm at 700 functions on one project with some patterns should drive TS insane.
Its always best to identify and solve the issue the second it appears as you can revert changes till you find it.
we actually have >500 functions, sorry.
here is tha convex AI agent reply:
Thanks for your comment; it was actually helpful @ampp . Turns out that v.array(v.any()), is ❌ Very dangerous