# How to Optimize Base Node Performance Through Cache Tuning: A Complete Guide

> Optimize Base Node performance via cache tuning. Configure GETH_CACHE env variables to efficiently allocate RAM for database, state trie, and GC, slashing disk I/O for faster sync and RPC.

- Repository: [Base/node](https://github.com/base/node)
- Tags: how-to-guide
- Published: 2026-03-03

---

**You can optimize Base Node performance through cache tuning by configuring the `GETH_CACHE` environment variables in your `.env` file to allocate RAM efficiently across the database, state trie, and garbage collection, significantly reducing disk I/O during sync and RPC operations.**

Base Node runs an Ethereum L2 execution client (Geth by default) inside Docker containers, making it straightforward to deploy but requiring careful memory configuration for optimal throughput. By understanding how to optimize Base Node performance through cache tuning, operators can leverage their hardware resources to achieve faster initial sync, lower latency on state queries, and more stable long-running operations.

## Understanding Geth Cache Architecture in Base Node

The Geth client inside Base Node exposes five primary cache parameters that control how RAM is partitioned across different subsystems. These values are defined in the repository's environment files and passed directly to the Geth binary at runtime.

In `geth/geth-entrypoint` (lines 17-22 and 83-87), the startup script reads environment variables and translates them into Geth command-line flags:

```bash
--cache="$GETH_CACHE" \
--cache.database="$GETH_CACHE_DATABASE" \
--cache.gc="$GETH_CACHE_GC" \
--cache.snapshot="$GETH_CACHE_SNAPSHOT" \
--cache.trie="$GETH_CACHE_TRIE"

```

### Key Cache Variables and Default Values

According to the source code in `.env.mainnet` (lines 60-66), Base Node ships with the following conservative defaults designed for ~20GB RAM allocation:

- **`GETH_CACHE`** (default: `20480`): Total cache size in megabytes (~20GB) used by Geth's internal cache manager
- **`GETH_CACHE_DATABASE`** (default: `20`): Percentage of total cache reserved for LevelDB database operations (4GB with default settings)
- **`GETH_CACHE_GC`** (default: `12`): Size in megabytes for the garbage collection cache
- **`GETH_CACHE_SNAPSHOT`** (default: `24`): Cache allocation for snapshot data used during fast sync
- **`GETH_CACHE_TRIE`** (default: `44`): Cache for the Merkle trie storing state and receipts

These defaults provide a baseline for general operation, but tuning them to match your specific hardware profile yields substantial performance gains.

## Why Cache Tuning Impacts Base Node Performance

Proper cache configuration directly affects three critical performance metrics for Base Node operators:

**Disk I/O Reduction**: Increasing `GETH_CACHE` allows more blockchain data to reside in RAM rather than being fetched from disk, which dramatically accelerates block import times during initial synchronization and catch-up syncs.

**State Access Latency**: The `GETH_CACHE_TRIE` parameter specifically caches the Merkle trie nodes, which are frequently accessed during transaction execution and RPC calls like `eth_getBalance` or `eth_call`. A larger trie cache reduces the need to traverse the LevelDB for state lookups.

**Sync Stability**: The `GETH_CACHE_SNAPSHOT` and `GETH_CACHE_GC` values influence how efficiently the node handles background tasks during fast sync. Insufficient cache here can cause the node to lag behind the chain tip or experience periodic stalls.

## Recommended Cache Settings by Available RAM

To optimize Base Node performance through cache tuning, map your host's total RAM to these recommended configurations, ensuring the sum of percentage-based sub-caches does not exceed 100% of `GETH_CACHE`:

| Host RAM | GETH_CACHE (MB) | GETH_CACHE_TRIE | GETH_CACHE_DATABASE | GETH_CACHE_SNAPSHOT | GETH_CACHE_GC |
|----------|----------------|-----------------|---------------------|---------------------|---------------|
| ≤ 16 GB | 8192 | 20 | 16 | 12 | 8 |
| 32 GB | 24576 | 48 | 24 | 28 | 12 |
| ≥ 64 GB | 40960 | 80 | 32 | 44 | 16 |

For hosts with more than 64GB of RAM, scale `GETH_CACHE` to approximately 60-70% of available memory while maintaining proportional sub-cache allocations.

## Configuring Cache Parameters in Base Node

Base Node consumes cache settings through environment variables defined in `.env.mainnet` or `.env.sepolia`. These files are sourced by Docker Compose and injected into the container at runtime.

### Modifying the Environment File

Locate the Geth cache section in your environment file and adjust values according to your hardware profile. For a 64GB host optimized for RPC workloads:

```dotenv

# GETH CACHE SETTINGS - Optimized for 64GB RAM

GETH_CACHE="32768"          # 32GB total cache

GETH_CACHE_DATABASE="32"    # 32% of total (~10GB) for LevelDB

GETH_CACHE_GC="16"          # 16MB garbage collection cache

GETH_CACHE_SNAPSHOT="40"    # 40MB snapshot cache

GETH_CACHE_TRIE="80"        # 80MB state trie cache (higher for RPC nodes)

```

After modifying the environment variables, restart the services to apply changes:

```bash
docker compose down
docker compose up --build -d

```

### Temporary Override Without File Modification

For testing or benchmarking different configurations without editing files, pass variables directly to the Docker Compose command:

```bash
CLIENT=geth \
GETH_CACHE=16384 \
GETH_CACHE_TRIE=64 \
GETH_CACHE_DATABASE=24 \
NETWORK_ENV=.env.mainnet \
docker compose up --build -d

```

This approach is useful for A/B testing sync performance with different cache allocations.

### Client Compatibility Considerations

When switching execution clients from Geth to alternatives like Reth or Nethermind, these specific `GETH_CACHE*` variables are ignored, as they are Geth-specific implementations. Reth handles memory optimization internally without manual cache tuning, while Nethermind uses its own configuration flags for memory management. Always consult the respective client documentation when running non-Geth configurations.

## Benchmarking Cache Tuning Results

To quantify the performance improvements from cache tuning, measure sync speed before and after configuration changes. Monitor block import times using the Geth console:

```bash
docker exec -it base-geth geth attach http://localhost:8545 \
  --exec 'debug.metrics(false).eth.db.chain.inserts'

```

Compare the average block processing time over a 10,000 block window. Well-tuned cache settings on adequate hardware typically show 2-4x faster sync speeds during the initial chain download compared to default configurations on under-provisioned systems.

## Summary

- **Base Node performance optimization** centers on five Geth cache variables defined in `.env.mainnet` or `.env.sepolia`
- **`GETH_CACHE`** controls total RAM allocation, while `GETH_CACHE_TRIE` and `GETH_CACHE_DATABASE` optimize state access and disk I/O respectively
- **Default settings** assume ~20GB RAM allocation; operators should scale these values to utilize 60-70% of available host memory
- **Configuration changes** require a container restart via `docker compose` to take effect
- **Alternative clients** (Reth, Nethermind) do not use these Geth-specific environment variables

## Frequently Asked Questions

### What happens if I set GETH_CACHE higher than my available RAM?

Setting `GETH_CACHE` higher than available physical memory will cause the Linux OOM (Out of Memory) killer to terminate the Geth process, or in containerized environments, the container will exit with an out-of-memory error. According to the `geth/geth-entrypoint` implementation, these values are passed directly to Geth without validation, so always ensure your total cache allocation leaves adequate headroom for the operating system and other processes.

### Can I tune Base Node cache settings while the node is running?

No, Geth reads cache parameters only at startup from the command-line flags defined in the entrypoint script. Changes to `GETH_CACHE` or related variables in your `.env` file require a full container restart using `docker compose down && docker compose up`. Hot-reloading of cache configurations is not supported by the underlying Geth client.

### How do I know if my current cache settings are too low?

Signs of insufficient cache include sustained high disk utilization (iops) during normal operation, slow response times on `eth_call` RPC methods, and the node falling behind the chain tip during sync despite adequate network bandwidth. You can verify cache pressure by attaching to the Geth console and checking if the database layer is performing frequent LevelDB compactions, which indicates the cache cannot hold the working set in memory.

### Do snapshot cache settings affect archive node performance?

The `GETH_CACHE_SNAPSHOT` parameter primarily impacts fast-sync and full-sync operations by caching snapshot data used for rebuilding the state trie. For archive nodes that maintain full historical state, the `GETH_CACHE_TRIE` setting is more critical for performance, as archive nodes perform extensive trie lookups for historical state queries. Increase `GETH_CACHE_TRIE` significantly (to 80-100MB or higher) when running an archive node with high RPC load.