apache/hadoop · error · RuntimeException

Total heap the can be used is {} bytes while the emulator is

Error message

Total heap the can be used is {} bytes while the emulator is configured to emulate a total of {} bytes

What it means

TotalHeapUsageEmulatorPlugin.initialize(monitor, totalHeapUsageInMB) compares the machine's physical memory (monitor.getPhysicalMemorySize() / ONE_MB) against the requested emulated heap usage in MB and throws RuntimeException if the target exceeds physical memory — the emulator allocates real objects, so it cannot emulate more heap than the box physically has. The message misleadingly says 'bytes' although both numbers are megabytes.

Source

Thrown at hadoop-tools/hadoop-gridmix/src/main/java/org/apache/hadoop/mapred/gridmix/emulators/resourceusage/TotalHeapUsageEmulatorPlugin.java:166

    /**
     * Gets the total number of 1mb objects stored in the emulator.
     *
     * @return total number of 1mb objects.
     */
    @VisibleForTesting
    public int getHeapSpaceSize() {
      return heapSpace.size();
    }

    /**
     * This will initialize the core and check if the core can emulate the 
     * desired target on the underlying hardware.
     */
    public void initialize(ResourceCalculatorPlugin monitor, 
                           long totalHeapUsageInMB) {
      long maxPhysicalMemoryInMB = monitor.getPhysicalMemorySize() / ONE_MB ;
      if(maxPhysicalMemoryInMB < totalHeapUsageInMB) {
        throw new RuntimeException("Total heap the can be used is " 
            + maxPhysicalMemoryInMB 
            + " bytes while the emulator is configured to emulate a total of " 
            + totalHeapUsageInMB + " bytes");
      }
    }
    
    /**
     * Clear references to all the GridMix-allocated special objects so that 
     * heap usage is reduced.
     */
    @Override
    public void reset() {
      heapSpace.clear();
    }
  }
  
  public TotalHeapUsageEmulatorPlugin() {
    this(new DefaultHeapUsageEmulator());

View on GitHub (pinned to 2add963021)

Solutions

1. Lower the emulated heap target (scale the trace's heap numbers down to fit the replay node, e.g. via a scale factor) so totalHeapUsageInMB <= physical memory MB
2. Run gridmix on nodes with at least as much physical RAM as the largest emulated heap
3. Disable heap emulation by removing TotalHeapUsageEmulatorPlugin from gridmix.emulators.resource-usage.plugins if heap fidelity is not required
4. Read the two numbers in the message as MB despite the word 'bytes'

Example fix

# before (on a 16GB node)
-Dgridmix.emulators.resource-usage.plugins=org.apache.hadoop.mapred.gridmix.emulators.resourceusage.TotalHeapUsageEmulatorPlugin
# trace job wants 64GB heap -> RuntimeException

# after: scale gridmix down to the node
-Dgridmix.submit.multiplier.interval=... 
# or scale heap targets (e.g. gridmix scale 0.1) / drop the plugin:
-Dgridmix.emulators.resource-usage.plugins=org.apache.hadoop.mapred.gridmix.emulators.resourceusage.CumulativeCpuUsageEmulatorPlugin

// Before running gridmix with heap emulation
long physicalMB = new LinuxResourceCalculatorPlugin().getPhysicalMemorySize() / (1024 * 1024);
if (targetHeapMB > physicalMB) {
  targetHeapMB = (long) (physicalMB * 0.8); // scale down to fit node
}

try {
  heapPlugin.initialize(monitor, totalHeapUsageInMB);
} catch (RuntimeException e) {
  // message numbers are MB despite saying 'bytes'; lower the emulated heap target
}

When it happens

Trigger: Configuring gridmix heap emulation with an emulated total-heap target (from the trace or gridmix.emulators.resource-usage.heap.* settings) larger than the physical RAM of the node running the task, e.g. a trace captured on a 512GB node replayed on a 16GB node with heap emulation enabled.

Common situations: Replaying production traces on smaller dev/test hardware; container memory limits conflated with physical memory (the check uses getPhysicalMemorySize, not container size); the 'bytes' vs 'MB' wording in the message confusing operators into misjudging the shortfall.

Related errors

• Misconfigured resource usage plugins. Class {} is not a reso
• getUsed on path `/' is not within a mount point
• Invalid capacity/limit
• Limit exceeds buffer size
• Too many splits

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/c4bc56caefd2daaa. Report an issue: GitHub.