How Motrix Handles DNS Fallback for Connectivity Issues Using dnsMode Settings

Motrix automatically falls back to the system DNS resolver when the dnsMode setting is configured to auto, enabling the Aria2 engine's c-ares async resolver with --async-dns=true, while system and engine modes disable fallback by forcing --async-dns=false.

Motrix is a full-featured, open-source download manager built on top of the Aria2 engine. When transient network issues cause DNS resolution to fail, Motrix provides robust DNS fallback capabilities through the configurable dnsMode setting, ensuring downloads remain resilient without manual intervention.

Understanding the Three dnsMode Options

Motrix exposes three distinct DNS resolution strategies through the dnsMode configuration option, defined in src/shared/schemas/engine-settings.ts (lines 22-27). Each mode maps directly to Aria2's --async-dns command-line flag via the dnsModeToAsyncDns() utility.

Auto Mode: Automatic Fallback Enabled

When dnsMode is set to auto (the default), Motrix enables Aria2's asynchronous DNS resolver powered by c-ares. This setting passes --async-dns=true to the Aria2 process, allowing the engine to first attempt resolution via c-ares. If the query fails with specific error codes such as EAI_AGAIN, EAI_FAIL, or EAI_NONAME, Aria2 automatically falls back to the host operating system's DNS resolver, providing seamless recovery from transient connectivity issues.

System Mode: OS Resolver Only

Setting dnsMode to system disables async-dns by passing --async-dns=false to Aria2. In this mode, all DNS lookups are delegated entirely to the host operating system's resolver. No Aria2-level fallback mechanism is active; the application relies solely on the OS DNS configuration without Motrix intervention.

Engine Mode: Built-in Resolution

The engine mode also sets --async-dns=false but instructs Motrix to use its own built-in DNS resolution logic rather than the system resolver. This mode is useful when users want Motrix to control DNS entirely, bypassing both the system resolver and Aria2's c-ares implementation.

Core Implementation Details

The DNS fallback mechanism involves several coordinated components across Motrix's codebase, from configuration building to error detection and IPC handling.

Mapping dnsMode to Aria2 Flags

The conversion logic resides in src/core/engine/aria2/dns-fallback.ts (lines 24-31). The dnsModeToAsyncDns() function translates the DnsResolutionMode enum into a boolean value:

// src/core/engine/aria2/dns-fallback.ts
export function dnsModeToAsyncDns(mode: DnsResolutionMode): boolean {
  // `auto` → enable async‑dns (c‑ares) so we can fall back to the system resolver
  // `system` or `engine` → disable async‑dns
  return mode === 'auto';
}

Building the Aria2 Configuration

When Motrix spawns an Aria2 instance, src/core/engine/aria2/aria2-config-builder.ts (lines 108-112) appends the DNS flag to the process arguments based on the user's settings:

// src/core/engine/aria2/aria2-config-builder.ts (excerpt)
const asyncDns = dnsModeToAsyncDns(settings.dnsMode);
args.push(`--async-dns=${asyncDns}`);

Detecting DNS Contact Failures

For the auto mode to trigger fallback correctly, Motrix must identify when c-ares has failed to contact DNS servers. The isDnsContactFailure() function in src/core/engine/aria2/dns-fallback.ts (lines 17-22) examines error messages using regex matching against standard c-ares error codes:

// src/core/engine/aria2/dns-fallback.ts (excerpt)
export function isDnsContactFailure(msg: string | null): boolean {
  if (!msg) return false;
  // c‑ares reports several error strings for contact failures
  return /^(EAI_AGAIN|EAI_FAIL|EAI_NONAME)/.test(msg);
}

Resetting the Fallback Latch

To ensure DNS fallback starts fresh when users change resolution modes, Motrix implements a "session latch" reset mechanism in both the main and server processes. In src/main/ipc/commands.ts (lines 150-155) and src/server/ipc/commands.ts (lines 66-71), the IPC command handlers detect dnsMode changes and reset the internal state:

// src/server/ipc/commands.ts (excerpt – handling mode change)
if (oldFull.engine.dnsMode !== newFull.engine.dnsMode) {
  dnsModeToAsyncDns(newFull.engine.dnsMode); // reset latch
}

This ensures that subsequent downloads respect the new configuration immediately without requiring an application restart.

Summary

• Motrix uses Aria2's c-ares resolver with --async-dns=true only when dnsMode is set to auto, enabling automatic fallback to the system DNS on resolution failures.
• Three modes control behavior: auto (fallback enabled), system (OS resolver only), and engine (Motrix built-in resolver).
• Error detection relies on c-ares codes: The isDnsContactFailure() function identifies EAI_AGAIN, EAI_FAIL, and EAI_NONAME errors to trigger fallback logic.
• Configuration is dynamic: Changing dnsMode via the settings UI immediately resets the session latch in both main and server processes, applying changes without restart.
• Default safety: The schema in engine-settings.ts defaults to auto, ensuring most users benefit from transparent DNS fault tolerance.

Frequently Asked Questions

What is the default dnsMode setting in Motrix?

According to the schema defined in src/shared/schemas/engine-settings.ts, the default value for dnsMode is auto. This ensures that new installations immediately benefit from Aria2's asynchronous DNS resolver with automatic fallback to the system resolver when c-ares encounters connectivity issues.

How does Motrix detect when to trigger DNS fallback?

Motrix uses the isDnsContactFailure() function in src/core/engine/aria2/dns-fallback.ts to inspect error messages from the c-ares library. If the error message matches patterns starting with EAI_AGAIN, EAI_FAIL, or EAI_NONAME, Motrix recognizes this as a DNS contact failure and triggers the fallback mechanism to retry with the system resolver.

What happens when I switch between dnsMode settings?

When you change the dnsMode setting in the Motrix UI, the IPC command handlers in both src/main/ipc/commands.ts and src/server/ipc/commands.ts detect the configuration change and reset the internal session latch. This ensures that any new download tasks immediately use the updated DNS resolution strategy without requiring you to restart the application.

Which dnsMode should I use for unreliable networks?

For unstable or unreliable network environments, auto mode is recommended because it provides transparent resilience. If the primary c-ares resolver fails to contact DNS servers (detected via isDnsContactFailure()), Motrix automatically falls back to the system resolver. Users experiencing specific issues with OS DNS caching or requiring custom resolution may prefer engine mode, while system mode is suitable for environments where the OS resolver is already optimized for the network.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}