Force IPv4 or IPv6 in Axios Using Family

When running network requests in Node.js, the Axios HTTP client relies on the operating system and Node's core networking stack to resolve domain names to IP addresses. In dual-stack network environments, automatic DNS resolution can occasionally lead to timeouts, routing failures, or unpredictable fallback behavior between IPv4 and IPv6. This article explains the role of the family option in network agents, how it determines IP resolution protocol, and how to configure Axios to strictly enforce either IPv4 or IPv6.

The Role of the family Parameter

In Node.js, DNS resolution is handled via the dns.lookup() method by default. When an HTTP or HTTPS request is dispatched without specific constraints, the resolver attempts to query both A (IPv4) and AAAA (IPv6) records. Depending on the environment, the system may prioritize IPv6, which can introduce latency or connection failures if the network or destination server has improper IPv6 routing.

The family option explicitly tells the underlying socket layer which IP version to request and bind. It accepts two primary integer values:

• 4: Forces DNS resolution to use IPv4 addresses only (A records).
• 6: Forces DNS resolution to use IPv6 addresses only (AAAA records).

By setting this value, you bypass the default address selection mechanism, ensuring that the HTTP client only connects through the specified Internet Protocol version.

Implementing family in Axios

Axios delegates transport-level networking in Node.js to the native http and https modules. To apply the family configuration to an Axios request, you define custom http.Agent and https.Agent instances containing the family property and attach them to your Axios configuration.

Forcing IPv4 Resolution

To ensure all outgoing requests strictly use IPv4, create agents with { family: 4 }:

const axios = require('axios');
const http = require('http');
const https = require('https');

const httpAgent = new http.Agent({ family: 4 });
const httpsAgent = new https.Agent({ family: 4 });

const client = axios.create({
  httpAgent,
  httpsAgent,
  timeout: 5000
});

async function fetchData() {
  try {
    const response = await client.get('https://api.example.com/data');
    console.log(response.data);
  } catch (error) {
    console.error('Request failed:', error.message);
  }
}

fetchData();

Forcing IPv6 Resolution

If your application operates in an IPv6-only infrastructure or needs to communicate with IPv6-specific services, change the family value to 6:

const httpAgent = new http.Agent({ family: 6 });
const httpsAgent = new https.Agent({ family: 6 });

const client = axios.create({
  httpAgent,
  httpsAgent
});

Applying per Request

You can also override the agent configuration on individual requests rather than defining it globally on an Axios instance:

axios.get('https://api.example.com/data', {
  httpsAgent: new https.Agent({ family: 4 })
});

Key Use Cases

1. Eliminating Latency and Timeouts: Systems attempting to connect over broken IPv6 routes often hang until an internal timeout triggers an IPv4 fallback. Setting family: 4 avoids this overhead entirely.
2. Legacy Infrastructure Compatibility: When integrating with internal services or APIs that lack IPv6 support, enforcing IPv4 guarantees consistent connectivity.
3. Targeted Testing: Setting family: 6 allows developers to test API availability over IPv6 explicitly without changing system-wide network adapter settings.