How to fix Error: Failed to write heap snapshot (disk space or permission) in Node.js

Node.jsINTERMEDIATEMEDIUM

This error occurs when Node.js cannot write a heap snapshot file using v8.writeHeapSnapshot(). It typically indicates insufficient disk space, lack of write permissions in the target directory, or insufficient memory to complete the snapshot operation.

What this error means

This error occurs when Node.js attempts to write a heap snapshot file but cannot complete the operation due to file system constraints. Heap snapshots are diagnostic files that capture the memory state of your Node.js application at a specific point in time, used primarily for debugging memory leaks and analyzing memory usage patterns. The v8.writeHeapSnapshot() function creates these snapshots, which can be quite large depending on your application's heap size. The operation requires not only disk space for the final snapshot file but also additional memory during the snapshot generation process—approximately twice the current heap size. This dual resource requirement makes the operation particularly susceptible to failures when system resources are constrained. This error can manifest as either an explicit error message or, in older Node.js versions, as a silent failure where the function returns undefined instead of throwing an error. Recent Node.js versions (v18+) have improved error reporting to make these failures more transparent.

How to fix "Error: Failed to write heap snapshot (disk space or permission)"

1Check available disk space

Verify that you have sufficient disk space where the snapshot will be written:

bash

# Check disk space on Linux/macOS
df -h

# Check space in specific directory
df -h /path/to/snapshot/directory

# On Windows (PowerShell)
Get-PSDrive

Ensure you have at least 2-3 times your application's heap size available. For example, if your Node.js process is using 2GB of heap memory, ensure at least 4-6GB of free disk space.

2Verify write permissions

Confirm that the Node.js process has write permissions in the target directory:

bash

# Check directory permissions
ls -la /path/to/snapshot/directory

# Test write access
touch /path/to/snapshot/directory/test.txt && rm /path/to/snapshot/directory/test.txt

# If needed, grant write permissions
chmod 755 /path/to/snapshot/directory

# Or change ownership to your Node.js process user
sudo chown node-user:node-group /path/to/snapshot/directory

3Specify an explicit directory with adequate resources

Use the filename parameter to write the snapshot to a directory with sufficient space and permissions:

javascript

const v8 = require('v8');
const path = require('path');
const fs = require('fs');

// Ensure directory exists
const snapshotDir = '/tmp/heapdumps';
if (!fs.existsSync(snapshotDir)) {
  fs.mkdirSync(snapshotDir, { recursive: true });
}

// Write snapshot with explicit path
const filename = path.join(snapshotDir, `heap-${Date.now()}.heapsnapshot`);

try {
  const result = v8.writeHeapSnapshot(filename);
  console.log('Heap snapshot written to:', result);
} catch (error) {
  console.error('Failed to write heap snapshot:', error.message);
  console.error('Error code:', error.code);
}

4Use --diagnostic-dir flag for automatic snapshots

When using automatic heap snapshot generation, specify a directory with adequate resources:

bash

# Start Node.js with diagnostic directory
node --diagnostic-dir=/var/tmp/diagnostics \
     --heapsnapshot-near-heap-limit=3 \
     app.js

# Or set via environment variable
export NODE_OPTIONS="--diagnostic-dir=/var/tmp/diagnostics"
node app.js

The --heapsnapshot-near-heap-limit flag controls how many snapshots to generate before the process exits when approaching heap limits. Setting it to 1-3 prevents overwhelming the system with multiple large files.

5Check and increase memory availability

Ensure sufficient memory is available for snapshot generation:

bash

# Increase Node.js heap size
node --max-old-space-size=4096 app.js

# Check available system memory
free -h  # Linux
vm_stat  # macOS

If running in a container, increase memory limits:

yaml

# Docker Compose
services:
  app:
    mem_limit: 4g
    memswap_limit: 4g

bash

# Docker run command
docker run --memory="4g" --memory-swap="4g" your-image

6Implement error handling and retry logic

Add proper error handling to gracefully handle snapshot failures:

javascript

const v8 = require('v8');
const fs = require('fs');

function writeHeapSnapshotSafely(directory = '/tmp') {
  try {
    // Check if directory is writable
    fs.accessSync(directory, fs.constants.W_OK);

    const filename = `${directory}/heap-${Date.now()}.heapsnapshot`;
    const result = v8.writeHeapSnapshot(filename);

    if (!result) {
      throw new Error('writeHeapSnapshot returned undefined');
    }

    console.log('Heap snapshot written successfully:', result);
    return result;

  } catch (error) {
    console.error('Failed to write heap snapshot:', error);

    // Try alternative directory
    if (directory !== '/tmp') {
      console.log('Retrying with /tmp directory...');
      return writeHeapSnapshotSafely('/tmp');
    }

    throw error;
  }
}

// Usage
writeHeapSnapshotSafely('/var/app/heapdumps');

7Check file system and ulimit constraints

Verify that system limits are not preventing file creation:

bash

# Check ulimit settings
ulimit -a

# Increase file size limit if needed
ulimit -f unlimited

# Check file system mount options
mount | grep "$(df . | tail -1 | awk '{print $1}')"

# Verify it's not a read-only file system
touch test.txt && rm test.txt

# Check disk quotas (if applicable)
quota -v

In containerized environments, ensure the file system is not mounted as read-only:

yaml

# Docker Compose - use volume for writable storage
volumes:
  - ./heapdumps:/app/heapdumps:rw

Advanced notes

Snapshot Generation Performance: Generating a heap snapshot is a synchronous operation that blocks the Node.js event loop. The duration depends on heap size—snapshots of multi-gigabyte heaps can take several seconds to complete. Avoid calling writeHeapSnapshot() in request handlers or performance-critical code paths. Instead, trigger it via signal handlers (SIGUSR2), administrative endpoints, or during low-traffic periods.

Memory Requirements: The snapshot generation process requires approximately twice the current heap size in available memory. This is because the V8 engine needs to traverse and serialize the entire heap while the application continues to hold existing objects. In memory-constrained environments, attempting to generate a snapshot can trigger OOM conditions, potentially causing the process to crash before the snapshot completes.

Worker Threads Consideration: Each Node.js worker thread has its own V8 isolate and separate heap. A heap snapshot generated from the main thread will not include data from worker threads. If you need to analyze worker thread memory, you must call writeHeapSnapshot() from within each worker separately.

Automatic Snapshot Generation: The --heapsnapshot-near-heap-limit flag enables automatic snapshot generation when the process approaches its heap limit. However, this can be problematic because the system is already under memory pressure when the snapshot is triggered. Set a low limit (1-3 snapshots) to prevent cascading failures where snapshot generation itself causes OOM errors.

Container Best Practices: In containerized deployments, mount a volume specifically for heap snapshots rather than writing to the container's writable layer. This prevents snapshots from consuming container disk space and allows snapshots to persist after container restarts. Consider using shared volumes or network file systems that can handle large files.

File Size Considerations: Heap snapshots can be extremely large, often matching or exceeding the heap size. A 2GB heap might produce a 1.5-2GB snapshot file. Plan storage accordingly and implement retention policies to prevent disk exhaustion. Consider compressing old snapshots or implementing automatic cleanup of snapshots older than a certain threshold.

Security Implications: Heap snapshots contain a complete dump of your application's memory, including potentially sensitive data like API keys, passwords, session tokens, and user data. Store snapshots securely with restricted permissions (chmod 600) and implement automatic cleanup. Never commit snapshot files to version control or transmit them over insecure channels.

Node.js Version Differences: Node.js versions before v18 had inconsistent error handling in writeHeapSnapshot(), sometimes returning undefined instead of throwing errors. Modern versions (v18+) provide better error reporting with proper error codes (ENOSPC, EACCES, etc.), making debugging easier. If using older versions, always check the return value for undefined in addition to catching errors.

How to fix Error: Failed to write heap snapshot (disk space or permission) in Node.js

What this error means

Typical symptoms

Common causes

How to fix "Error: Failed to write heap snapshot (disk space or permission)"

Advanced notes

Related errors

Official resources & further reading