How Axios Handles Chunked Transfer Encoding

This article provides an overview of how the Axios HTTP client processes HTTP responses that use chunked transfer encoding (Transfer-Encoding: chunked). It details the default behavior of Axios across different runtime environments—Node.js and the browser—explains how data is buffered versus streamed, and demonstrates how to handle streaming data efficiently without running into memory bottlenecks.

Default Behavior: Response Buffering

By default, Axios automatically buffers chunked responses. When a server responds with Transfer-Encoding: chunked without a predefined Content-Length header, Axios listens for incoming data chunks, stitches them together in memory, and resolves the promise only after the entire response stream has finished.

For standard configurations (such as responseType: 'json' or responseType: 'text'), response.data will contain the fully assembled and parsed payload rather than individual chunks.

Behavior in Node.js

In a Node.js environment, Axios relies on the native http and https modules.

1. Default Mode (Buffered)

Axios accumulates all chunks emitted by the underlying http.IncomingMessage stream. Once the stream ends, it formats the result based on the specified responseType and resolves the request promise.

2. Streaming Mode (responseType: 'stream')

To process chunks in real time as they arrive from the server, you must set the responseType configuration to 'stream'.

const axios = require('axios');

async function downloadStream() {
  const response = await axios({
    method: 'get',
    url: 'https://example.com/large-chunked-data',
    responseType: 'stream'
  });

  // response.data is a readable stream
  response.data.on('data', (chunk) => {
    console.log(`Received chunk: ${chunk.length} bytes`);
  });

  response.data.on('end', () => {
    console.log('Stream finished.');
  });
}

Using 'stream' prevents high memory consumption when handling large payloads, such as video streams or massive datasets.

Behavior in the Browser

In the browser, Axios predominantly relies on the XMLHttpRequest (XHR) API, though newer configurations can use the Fetch API adapter.

• XMLHttpRequest: Standard XHR does not support full readable streams. Axios waits until readyState === 4 (the transfer is complete) before resolving the response promise, buffering the entire chunked payload in browser memory.
• Fetch Adapter: When configured to use the modern Fetch API adapter with ReadableStreams, Axios can expose browser-compatible streams, but the default distribution still behaves synchronously with respect to promise resolution for standard response types.

Important Considerations

• Memory Usage: Buffering large chunked responses in default mode can cause high memory usage or out-of-memory errors in both Node.js and browser environments.
• Timeouts: The Axios timeout setting applies to the entire request lifecycle. If a chunked response streams slowly over a prolonged period, the request may trigger a timeout unless the timeout value is explicitly disabled or increased.
• Error Handling: If the connection terminates prematurely before the final zero-length chunk is received, Axios will reject the promise or emit an error on the stream, flagging an incomplete or malformed transfer.