discord.js v14 makeCache LimitedCollection memory versus REST cache-miss trade-off

Question

The goal is to decide whether to cap discord.js v14 in-memory caches with makeCache and LimitedCollection to reduce hosting cost for a low-traffic bot. By default, discord.js v14 retains guilds, users, messages, and other entities in memory, so resident memory can grow as the client sees new IDs even when message volume is low.

Smaller caches lower instance size requirements but increase cache-miss REST fetches, consuming rate-limit budget and adding latency. Memory also scales with shard count because each shard keeps its own caches, so per-shard limits must be multiplied for total RAM estimates. It is unclear which maxSize values avoid evicting actively reused entities while still cutting cost.

Will bounding cache managers with LimitedCollection reduce resident memory without causing repeated refetch of the same entities? Does cache-miss REST traffic eventually cost more than the hosting savings from a smaller instance? Should per-shard maxSize values be summed across shards when estimating total container or VM memory?

Tasadduq Burney · Answer

Bounding cache managers with LimitedCollection will successfully reduce resident memory, but it introduces a risk of repeated REST fetches for frequently evicted entities. For a low-traffic bot, this is usually a viable strategy to fit into cheaper hosting tiers, provided the maxSize is tuned to hold your 'active working set.'

The Memory-Latency Trade-off
In discord.js v14, the default cache grows indefinitely as the bot encounters new Discord entities. By using makeCache with a LimitedCollection, you enforce a hard cap on the number of objects stored in memory per shard.n
  Memory Savings: Resident heap usage is capped, preventing OOM-related crashes on low-RAM instances.
  Latency Penalty: When an entity is evicted, subsequent calls to guild.fetch() or user.fetch() will trigger an asynchronous REST request. This adds milliseconds of latency and consumes your API rate-limit budget.

If your maxSize is smaller than the number of users or guilds your bot interacts with hourly, you will suffer from 'thrashing' where the bot constantly deletes and refetches the same data, leading to degraded performance.

Sharding and Estimation
Yes, you must sum the maxSize values across all shards when estimating total memory. Since each shard maintains its own instance of the cache, the total memory footprint is multiplicative:

Total RAM ≈ (Sum of maxSize for all caches) * Number of Shards + Base Node.js Overhead

Implementation Strategy
To implement this safely, configure the caches during the Client initialization:
nconst { Client, GatewayIntentBits, Collection } = require('discord.js');

const client = new Client({
  intents: [/* ... */],
  cache: {
    guilds: makeCache(LimitedCollection, { maxSize: 50 }),
    users: makeCache(LimitedCollection, { maxSize: 1000 }),
    messages: makeCache(LimitedCollection, { maxSize: 50 })
  }
});

To determine the optimal maxSize, monitor the number of unique guilds or users your bot interacts with during a peak hour and set the limit slightly above that number to avoid constant eviction.

Diagnostic Question: Is your bot currently running on a single shard, or is it auto-sharded? This determines how aggressively you must lower your limits.

discord.js v14 makeCache LimitedCollection memory versus REST cache-miss trade-off

1 answer

The Memory-Latency Trade-off

Sharding and Estimation

Implementation Strategy

Your perspective belongs here.

0 question comments