chore: warn when heap limit is too low

docs/pages/faqs.md

@@ -4,6 +4,19 @@ This section of the documentation will cover common questions and encounters oft
 
 ## Troubleshooting Lodestar
 
+### Running a beacon node
+
+:::note "Heap memory limit"
+Lodestar beacon node requires at least 8GB of heap space. While the `lodestar` script and the official docker image correctly sets the appropriate value, it might be necessary to manually set it for some specific scenario.
+
+The simplest way to achieve this is via the `NODE_OPTIONS` environment variable or by passing [`--max-old-space-size`](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes) directly to the node binary
+
+```bash
+NODE_OPTIONS: --max-old-space-size=8192
+```
+
+:::
+
 ### Using Kubernetes
 
 :::note "Unknown arguments error"

packages/cli/src/cmds/beacon/handler.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import {getHeapStatistics} from "node:v8";
 import {Registry} from "prom-client";
 import {ErrorAborted} from "@lodestar/utils";
 import {LevelDbController} from "@lodestar/db";
@@ -28,13 +29,21 @@ import {initPeerIdAndEnr} from "./initPeerIdAndEnr.js";
 
 const DEFAULT_RETENTION_SSZ_OBJECTS_HOURS = 15 * 24;
 const HOURS_TO_MS = 3600 * 1000;
+const EIGHT_GB = 8 * 1024 * 1024 * 1024;
 
 /**
  * Runs a beacon node.
  */
 export async function beaconHandler(args: BeaconArgs & GlobalArgs): Promise<void> {
   const {config, options, beaconPaths, network, version, commit, peerId, logger} = await beaconHandlerInit(args);
 
+  const heapSizeLimit = getHeapStatistics().heap_size_limit;
+  if (heapSizeLimit < EIGHT_GB) {
+    logger.warn(
+      `Node.js heap size limit is too low, consider increasing it to at least ${EIGHT_GB}. See https://chainsafe.github.io/lodestar/faqs#running-a-node for more details.`
+    );
+  }
+
   // initialize directories
   mkdir(beaconPaths.dataDir);
   mkdir(beaconPaths.beaconDir);