RangeError Map maximum size exceeded when uploading a file

TL;DR

V8 Maps cap out at about 16.7 million entries, and the crash means some code is putting one entry per chunk, byte range, or progress tick into a single Map during the upload. Find the Map that tracks upload state, then stop letting it grow without bound: key by chunk index in a bounded window, use a plain array or a Set of pending chunks, or clear completed chunks as each part is confirmed.

Error

RangeError: Map maximum size exceeded when uploading a file

Steps

1. Confirm the failing Map is upload state, not the file data. Open the failing call in the stack trace and look for a Map that gains an entry per chunk, per byte range, or per progress callback (names like pendingChunks, chunkStatus, uploadedParts, partETags are common). Expected output: you can point at one Map whose size grows steadily as the upload progresses.
2. Reproduce with logging instead of guessing. Log mapName.size every N chunks during an upload and watch whether it climbs without ever dropping. Expected output: the size increases monotonically through the transfer and the crash happens when it nears 2^24 entries (about 16.7M).
3. Fix it by deleting completed entries. If the Map tracks in-flight chunks, delete the key as soon as the chunk is acknowledged:

async function uploadChunk(index, data) {
  pendingChunks.set(index, true);
  try {
    await putChunk(index, data);
  } finally {
    pendingChunks.delete(index); // keep the Map at window size, not file size
  }
}

Expected output: the Map size stays bounded by your concurrency window instead of the file size, and the upload completes.

4. If the Map is an index of all parts (for example part number to ETag for a multipart complete call), keep only what you need. Store part number and ETag in a plain array; arrays have the same element limit but the usual failure mode here is keyed lookups that never clean up. For resumable uploads, persist completed parts to disk or IndexedDB, not to a growing in-memory Map. Expected output: memory stays flat for the whole transfer.
5. For uploads driven by progress callbacks, stop keying progress by timestamp. A progress handler that does progress.set(Date.now(), bytesSent) can add thousands of entries per second; use a single object that you overwrite, or a counter plus the last known byte count. Expected output: the callback overhead drops and the RangeError goes away.

When to use

• The upload crashes with RangeError: Map maximum size exceeded partway through large files
• You chunk uploads client-side and track per-chunk state in a Map
• Small files upload fine and large files always crash at roughly the same point

When not to use

• The error appears on page load with no upload running (that is a different Map overflowing elsewhere; the same fix pattern applies, but the upload steps do not)
• The upload fails with a network error or a 4xx/5xx status (that is the server or the network, not a client-side Map)
• Memory climbs because you hold the whole file in memory (switch to streaming the file with Blob slicing or ReadableStream instead)

Variant phrasings

RangeError Map maximum size exceeded in a multipart upload

Same root cause: the parts Map never drops finished parts. Delete entries on acknowledgment, or keep part metadata in an array.

Upload crashes only for files above a certain size

The threshold is entry count, not bytes: more chunks means more entries. Fewer, larger chunks also reduce the Map size, but bounding the Map is the real fix.

Map maximum size exceeded in an Electron or Node upload worker

The V8 limit applies in Node and Electron too. The same in-memory Map patterns cause it; the same bounded-window fix works.

Why it happens

V8 caps a Map at 2^24 entries (16,777,216). Upload code often builds a Map that mirrors the transfer: one key per chunk, per part, or per progress event. For small files the Map stays tiny and nobody notices; for large files, small chunks, or noisy progress callbacks, the entry count hits the cap and V8 throws instead of growing the Map. The crash is a state-management bug, not a file-size limit.

Edge cases

• If chunks are retried, a retry must not re-add a key the first attempt already cleaned up; guard with a check or use the window pattern so retries replace, not accumulate.
• Parallel uploads sharing one global Map multiply the entry count; scope the state Map per upload instead.
• Some libraries build the Map internally. If you cannot change the code, reduce the concurrency or increase the chunk size to stay under the entry cap, then file the issue against the library with your entry-count measurements.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8VEiV43BNaIwoQtNRazZag