Fixing XMLHttpRequest Timeout Errors for Large File Uploads #

Resolving net::ERR_CONNECTION_TIMED_OUT and ontimeout events requires isolating the failure boundary. Large payloads trigger browser socket exhaustion, reverse proxy limits, or backend processing delays. Understanding the underlying Upload Fundamentals & Browser APIs is critical for diagnosing network stack bottlenecks before implementing client-side retry mechanisms.

This guide provides exact diagnostic steps, production-ready timeout configuration, and chunking strategies. You will learn when to migrate to modern promise-based APIs and how to prevent silent connection drops.

Diagnosing XHR Timeout Triggers #

Isolate the timeout origin before adjusting client thresholds. The browser, a reverse proxy, or the backend pipeline can each drop the connection independently.

Monitor xhr.readyState transitions during the upload lifecycle. A timeout typically triggers xhr.status === 0 with an empty response body. Differentiate this from a server-side 504 Gateway Timeout, which returns an explicit HTTP status.

Use the following diagnostic wrapper to capture exact failure states and measure elapsed time:

function diagnoseXHR(file, endpoint) {
 const xhr = new XMLHttpRequest();
 const startTime = performance.now();
 
 xhr.open('POST', endpoint, true);
 xhr.timeout = 60000; // Initial diagnostic threshold
 
 xhr.onreadystatechange = () => {
 const elapsed = Math.round(performance.now() - startTime);
 console.log(`[XHR] readyState: ${xhr.readyState}, status: ${xhr.status}, elapsed: ${elapsed}ms`);
 
 if (xhr.readyState === 4) {
 if (xhr.status === 0) {
 console.warn('[XHR] Client-side timeout or network abort detected.');
 } else if (xhr.status >= 500) {
 console.error(`[XHR] Server error: ${xhr.status} after ${elapsed}ms`);
 }
 }
 };

 xhr.ontimeout = () => {
 const elapsed = Math.round(performance.now() - startTime);
 console.error(`[XHR] ontimeout fired at ${elapsed}ms. Check reverse proxy idle_timeout.`);
 };

 xhr.onerror = (e) => console.error('[XHR] Network error:', e);
 
 const formData = new FormData();
 formData.append('file', file);
 xhr.send(formData);
}

Inspect the Network tab for pending state duration. Compare it against the actual TCP handshake time. If the connection hangs before sending headers, the issue is local DNS or firewall rules. If it hangs during transmission, inspect proxy keep-alive settings.

Configuring Timeout & Retry Logic #

Implement explicit timeout thresholds and exponential backoff. Relying on default browser limits causes silent failures under variable network conditions. Proper Browser Timeout & Retry Logic ensures resilient uploads without overwhelming the network stack.

Wrap xhr.send in a controlled retry loop. Increment the timeout per attempt and apply jitter to prevent thundering herd scenarios. Always clear pending instances before retrying.

async function uploadWithRetry(file, endpoint, maxRetries = 3) {
 let attempt = 0;
 let baseTimeout = 30000;
 
 while (attempt <= maxRetries) {
 const xhr = new XMLHttpRequest();
 xhr.open('POST', endpoint, true);
 xhr.timeout = baseTimeout * Math.pow(2, attempt);
 
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), xhr.timeout);
 
 try {
 await new Promise((resolve, reject) => {
 xhr.onload = () => {
 clearTimeout(timeoutId);
 if (xhr.status >= 200 && xhr.status < 300) resolve(xhr.response);
 else reject(new Error(`HTTP ${xhr.status}`));
 };
 xhr.ontimeout = () => reject(new Error('XHR_TIMEOUT'));
 xhr.onerror = () => reject(new Error('NETWORK_ERROR'));
 xhr.send(new FormData().append('file', file));
 });
 return 'Success';
 } catch (err) {
 xhr.abort(); // Critical: release socket and memory
 attempt++;
 const jitter = Math.random() * 1000;
 console.warn(`[Retry] Attempt ${attempt} failed: ${err.message}. Waiting ${jitter}ms.`);
 await new Promise(res => setTimeout(res, jitter));
 }
 }
 throw new Error('Max retries exceeded');
}

Track retry metrics in your observability platform. Log attempt counts, timeout durations, and final failure states. This data reveals whether the bottleneck is network latency or server processing capacity.

Chunked Binary Upload Implementation #

Bypass single-request limits by splitting File objects into Blob slices. Sequential transmission prevents memory pressure and reduces connection drop probability. Target 5MB to 10MB chunks for optimal throughput.

Use file.slice for memory-efficient partitioning. Track the byte offset and resume transmission on ontimeout. Maintain server-side assembly state using Content-Range headers.

class ChunkedUploader {
 constructor(file, endpoint, chunkSize = 5 * 1024 * 1024) {
 this.file = file;
 this.endpoint = endpoint;
 this.chunkSize = chunkSize;
 this.offset = 0;
 this.uploadId = crypto.randomUUID();
 }

 async start() {
 while (this.offset < this.file.size) {
 const chunk = this.file.slice(this.offset, this.offset + this.chunkSize);
 await this.sendChunk(chunk);
 this.offset += chunk.size;
 }
 console.log('[Upload] Complete. Total bytes:', this.file.size);
 }

 async sendChunk(chunk) {
 return new Promise((resolve, reject) => {
 const xhr = new XMLHttpRequest();
 xhr.open('PATCH', `${this.endpoint}/${this.uploadId}`, true);
 xhr.timeout = 45000;
 xhr.setRequestHeader('Content-Range', `bytes ${this.offset}-${this.offset + chunk.size - 1}/${this.file.size}`);
 
 xhr.ontimeout = () => {
 xhr.abort();
 reject(new Error(`Chunk timeout at offset ${this.offset}`));
 };
 xhr.onerror = () => reject(new Error('Network failure'));
 xhr.onload = () => {
 if (xhr.status === 200 || xhr.status === 201) resolve();
 else reject(new Error(`Server rejected chunk: ${xhr.status}`));
 };
 
 xhr.send(chunk);
 });
 }
}

Server-side endpoints must validate Content-Range headers. Store partial chunks in temporary storage. Assemble the final payload only after receiving the last chunk and verifying checksums.

Modern Fetch API Migration #

Transition legacy workflows to fetch with AbortController for native timeout management. Promise-based syntax simplifies error handling and reduces callback nesting. Streaming ReadableStream objects further reduce main-thread blocking.

Replace xhr.timeout with AbortSignal.timeout. Handle multipart boundaries manually via FormData. Note that fetch lacks granular upload progress events, requiring custom stream tracking for large files.

async function uploadWithFetch(file, endpoint) {
 const formData = new FormData();
 formData.append('file', file);
 
 const controller = new AbortController();
 const timeoutSignal = AbortSignal.timeout(30000);
 controller.signal.addEventListener('abort', () => console.log('[Fetch] Aborted'));
 
 try {
 const response = await fetch(endpoint, {
 method: 'POST',
 body: formData,
 signal: AbortSignal.any([controller.signal, timeoutSignal])
 });
 
 if (!response.ok) throw new Error(`HTTP ${response.status}`);
 return await response.json();
 } catch (err) {
 if (err.name === 'AbortError') {
 console.error('[Fetch] Timeout or manual abort triggered.');
 } else {
 console.error('[Fetch] Upload failed:', err.message);
 }
 throw err;
 }
}

Use fetch for standard payloads under 50MB. Retain XHR only when precise upload progress tracking is mandatory. Combine AbortSignal with service workers for background retry orchestration.

Common Pitfalls & Edge Cases #

Base64 Encoding Overhead: Converting binary files to Base64 increases payload size by approximately 33%. This drastically extends transmission time and triggers browser timeouts prematurely. Always transmit raw Blob or ArrayBuffer objects. Use FormData with multipart/form-data headers for native streaming.

Ignoring Reverse Proxy Timeouts: Client-side xhr.timeout may be set to 60s, but Nginx or Cloudflare defaults to 30s. This causes silent 504 drops before the ontimeout event fires. Align client thresholds with proxy_read_timeout and idle_timeout. Implement server-side async processing or presigned URLs for files exceeding 100MB.

Memory Leaks from Unclosed XHR Instances: Repeatedly instantiating new XMLHttpRequest objects inside a retry loop without calling xhr.abort() causes socket exhaustion. Explicitly invoke xhr.abort() in catch and ontimeout blocks. Implement a singleton request manager to track and terminate active instances.

Frequently Asked Questions