diff --git a/docs/pages/faqs.md b/docs/pages/faqs.md index 01732c5c11fa..d86f2a37471e 100644 --- a/docs/pages/faqs.md +++ b/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" diff --git a/packages/cli/src/cmds/beacon/handler.ts b/packages/cli/src/cmds/beacon/handler.ts index 1ffde48133cb..444bbba8510e 100644 --- a/packages/cli/src/cmds/beacon/handler.ts +++ b/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,6 +29,7 @@ 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. @@ -35,6 +37,13 @@ const HOURS_TO_MS = 3600 * 1000; export async function beaconHandler(args: BeaconArgs & GlobalArgs): Promise { 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);