fix(DX-10060): retry transient network errors to prevent build crashes

Transient network-layer errors (ENOTFOUND, ENETUNREACH, ECONNRESET,
ECONNREFUSED, EAI_AGAIN, ETIMEDOUT, EHOSTUNREACH, ENETDOWN) now trigger
the SDK's configured retry policy instead of failing immediately.

A combinedRetryCondition composes the user-supplied retryCondition with
the new default network-error check. The user condition runs first; if it
throws, a warning is emitted via logHandler and the SDK falls back to the
default. The original config object is never mutated.

ECONNABORTED is excluded — @contentstack/core classifies it as a
structured TIMEOUT error and handles it separately.

Resolves: SF Case #00060601 (SentinelOne)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: OMpawar-21

CHANGELOG.md

@@ -1,3 +1,8 @@
+### Version: 5.5.1
+#### Date: Aug-03-2026
+Fix: Transient network-layer errors (ENOTFOUND, ENETUNREACH, ECONNRESET, ECONNREFUSED, EAI_AGAIN, ETIMEDOUT, EHOSTUNREACH, ENETDOWN) are now retried automatically using the SDK's configured retry policy instead of failing immediately.
+Enhancement: User-supplied `retryCondition` is composed with the default network-error retry logic — both are honoured without either replacing the other. If `retryCondition` throws, the SDK logs a warning via `logHandler` and falls back to default retry behaviour.
+
 ### Version: 5.5.0
 #### Date: Jul-27-2026
 Enhancement: Entry variants support an optional branch name as the second argument to `variants()` on `Entry` and `Entries`. When provided, the branch is sent as the `branch` request header together with `x-cs-variant-uid`. Existing `variants(uid)` and `variants(uids)` calls remain backward compatible. Added unit and API tests for variant + branch requests.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentstack/delivery-sdk",
-  "version": "5.5.0",
+  "version": "5.5.1",
   "type": "module",
   "license": "MIT",
   "engines": {

src/common/utils.ts

@@ -16,27 +16,20 @@ export function isBrowser() {
 }
 
 /**
- * Node.js/libuv error codes representing transient, retryable network-layer
- * failures (DNS resolution, connection reset/refused, no route to host, etc.),
- * plus Axios's own client-side timeout/abort signal ('ECONNABORTED'). All of
- * these occur before an HTTP response is received, so `error.response` is
- * undefined for all of them.
- *
- * 'ECONNABORTED' is included deliberately: @contentstack/core's own timeout
- * handling never retries it (it throws immediately on the first occurrence),
- * so without this, a single transient timeout has the same crash-the-caller
- * effect as an unretried DNS failure.
+ * Node.js/libuv error codes that represent transient, retryable network-layer
+ * failures. All occur before an HTTP response is received (error.response is
+ * undefined). ECONNABORTED is excluded — @contentstack/core handles it as a
+ * structured TIMEOUT error and it should not be retried here.
  */
 export const TRANSIENT_NETWORK_ERROR_CODES: ReadonlySet<string> = new Set([
-  'ENOTFOUND',
-  'ENETUNREACH',
-  'ECONNRESET',
-  'ECONNREFUSED',
-  'EAI_AGAIN',
-  'ETIMEDOUT',
-  'EHOSTUNREACH',
-  'ENETDOWN',
-  'ECONNABORTED',
+  'ENOTFOUND',    // DNS resolution failed
+  'ENETUNREACH',  // no route to host
+  'ECONNRESET',   // connection reset mid-flight
+  'ECONNREFUSED', // port closed / service not listening
+  'EAI_AGAIN',    // DNS server returned SERVFAIL (transient)
+  'ETIMEDOUT',    // OS-level connection timeout
+  'EHOSTUNREACH', // no route to host at IP layer
+  'ENETDOWN',     // local network interface down
 ]);
 
 /**

src/stack/contentstack.ts

@@ -178,8 +178,10 @@ export function stack(config: StackConfig): StackClass {
   // itself is never mutated, so stack.config / client.defaults keep reflecting
   // exactly what the consumer passed in.
   const combinedRetryCondition = (error: any) => {
-    if (config.retryCondition && config.retryCondition(error)) {
-      return true;
+    try {
+      if (config.retryCondition?.(error)) return true;
+    } catch (e) {
+      config.logHandler?.('warn', `[Contentstack SDK] retryCondition callback threw: "${(e as Error)?.message ?? e}". Check your retryCondition implementation. Falling back to default network-error retry behavior.`);
     }
     return Utility.isTransientNetworkError(error);
   };

test/unit/network-error-retry.spec.ts

@@ -21,9 +21,9 @@ describe('Default network-error retry behavior', () => {
 
   it('(a) retries and succeeds after a single transient ENOTFOUND failure with no custom retryCondition', async () => {
     const config: StackConfig = {
-      apiKey: 'test-api-key',
-      deliveryToken: 'test-delivery-token',
-      environment: 'test-environment',
+      apiKey: 'TEST-API-KEY',
+      deliveryToken: 'TEST-DELIVERY-TOKEN',
+      environment: 'TEST-ENVIRONMENT',
       retryDelay: 10,
     };
     const stack = Contentstack.stack(config);
@@ -42,9 +42,9 @@ describe('Default network-error retry behavior', () => {
 
   it('(b) still fails after retryLimit is exhausted on a permanent network failure', async () => {
     const config: StackConfig = {
-      apiKey: 'test-api-key',
-      deliveryToken: 'test-delivery-token',
-      environment: 'test-environment',
+      apiKey: 'TEST-API-KEY',
+      deliveryToken: 'TEST-DELIVERY-TOKEN',
+      environment: 'TEST-ENVIRONMENT',
       retryLimit: 2,
       retryDelay: 10,
     };
@@ -60,9 +60,9 @@ describe('Default network-error retry behavior', () => {
   it('(c) composes with a user-supplied retryCondition without replacing it', async () => {
     const userCondition = jest.fn((error: any) => error?.response?.status === 500);
     const config: StackConfig = {
-      apiKey: 'test-api-key',
-      deliveryToken: 'test-delivery-token',
-      environment: 'test-environment',
+      apiKey: 'TEST-API-KEY',
+      deliveryToken: 'TEST-DELIVERY-TOKEN',
+      environment: 'TEST-ENVIRONMENT',
       retryDelay: 10,
       retryCondition: userCondition,
     };
@@ -84,11 +84,14 @@ describe('Default network-error retry behavior', () => {
     expect(stack.config.retryCondition).toBe(userCondition);
   });
 
-  it('(d) ECONNABORTED/timeout errors are unaffected by the new network-retry path', async () => {
+  it('(d) ECONNABORTED (axios timeout) is NOT retried — core classifies it as a structured TIMEOUT error', async () => {
+    // ECONNABORTED is excluded from TRANSIENT_NETWORK_ERROR_CODES so that
+    // @contentstack/core can surface it as { error_code: "TIMEOUT" } (#239).
+    // Retrying it here would bypass that structured classification.
     const config: StackConfig = {
-      apiKey: 'test-api-key',
-      deliveryToken: 'test-delivery-token',
-      environment: 'test-environment',
+      apiKey: 'TEST-API-KEY',
+      deliveryToken: 'TEST-DELIVERY-TOKEN',
+      environment: 'TEST-ENVIRONMENT',
       retryDelay: 10,
     };
     const stack = Contentstack.stack(config);
@@ -99,4 +102,95 @@ describe('Default network-error retry behavior', () => {
 
     await expect(client.get('/content_types/test')).rejects.toBeDefined();
   });
+
+  it('(e) ENETUNREACH and ETIMEDOUT (the customer-reported codes) are retried', async () => {
+    for (const code of ['ENETUNREACH', 'ETIMEDOUT'] as const) {
+      const config: StackConfig = {
+        apiKey: 'TEST-API-KEY',
+        deliveryToken: 'TEST-DELIVERY-TOKEN',
+        environment: 'TEST-ENVIRONMENT',
+        retryDelay: 10,
+      };
+      const stack = Contentstack.stack(config);
+      const client = stack.getClient();
+      const mock = new MockAdapter(client);
+
+      mock
+        .onGet('/content_types/test')
+        .replyOnce(dnsError(code))
+        .onGet('/content_types/test')
+        .reply(200, { content_types: [] });
+
+      const res = await client.get('/content_types/test');
+      expect(res.status).toBe(200);
+      mock.restore();
+    }
+  });
+
+  it('(f) EAI_AGAIN (DNS servfail, intermittent) is retried', async () => {
+    const config: StackConfig = {
+      apiKey: 'TEST-API-KEY',
+      deliveryToken: 'TEST-DELIVERY-TOKEN',
+      environment: 'TEST-ENVIRONMENT',
+      retryDelay: 10,
+    };
+    const stack = Contentstack.stack(config);
+    const client = stack.getClient();
+    mockClient = new MockAdapter(client);
+
+    mockClient
+      .onGet('/content_types/test')
+      .replyOnce(dnsError('EAI_AGAIN'))
+      .onGet('/content_types/test')
+      .reply(200, { content_types: [] });
+
+    const res = await client.get('/content_types/test');
+    expect(res.status).toBe(200);
+  });
+
+  it('(g) retryOnError: false disables network-error retries — ENOTFOUND throws immediately', async () => {
+    const config: StackConfig = {
+      apiKey: 'TEST-API-KEY',
+      deliveryToken: 'TEST-DELIVERY-TOKEN',
+      environment: 'TEST-ENVIRONMENT',
+      retryOnError: false,
+      retryDelay: 10,
+    };
+    const stack = Contentstack.stack(config);
+    const client = stack.getClient();
+    mockClient = new MockAdapter(client);
+
+    // Second route intentionally registered — if the SDK retried it would succeed,
+    // proving the test would only pass when retryOnError: false truly disables retry.
+    mockClient
+      .onGet('/content_types/test')
+      .replyOnce(dnsError('ENOTFOUND'))
+      .onGet('/content_types/test')
+      .reply(200, { content_types: [] });
+
+    await expect(client.get('/content_types/test')).rejects.toBeDefined();
+  });
+
+  it('(h) retryLimit: 0 disables network-error retries — ENOTFOUND throws immediately', async () => {
+    const config: StackConfig = {
+      apiKey: 'TEST-API-KEY',
+      deliveryToken: 'TEST-DELIVERY-TOKEN',
+      environment: 'TEST-ENVIRONMENT',
+      retryLimit: 0,
+      retryDelay: 10,
+    };
+    const stack = Contentstack.stack(config);
+    const client = stack.getClient();
+    mockClient = new MockAdapter(client);
+
+    // Second route intentionally registered — if the SDK retried it would succeed,
+    // proving the test would only pass when retryLimit: 0 truly disables retry.
+    mockClient
+      .onGet('/content_types/test')
+      .replyOnce(dnsError('ENOTFOUND'))
+      .onGet('/content_types/test')
+      .reply(200, { content_types: [] });
+
+    await expect(client.get('/content_types/test')).rejects.toBeDefined();
+  });
 });