The default maxCachedWorkflows formula uses maxHeapMemory (--max-old-space-size) to calculate
how many workflows to cache. However, workflow VM isolates allocate native memory outside
the V8 heap, not inside it.
This causes unexpected OOMs in containerized environments where:
- --max-old-space-size is set high (e.g., 4.6GB) relative to container limit (5Gi)
- Temporal calculates maxCachedWorkflows = ~2600
- VM isolates consume ~2.6GB of NATIVE memory (not heap)
- Total memory = heap + VM cache + overhead > container limit → OOMKill
Suggested improvements:
- Documentation: Warn that VM isolates use native memory, not heap memory
- Default calculation: Consider using a more conservative default, or factor in
that VM cache is additive to heap usage
- Logging: Log a warning if calculated maxCachedWorkflows * ~1MB + maxHeapMemory
exceeds available system memory
Environment: TypeScript SDK 1.11.7, Node.js 22, Kubernetes