# How Motrix Handles DNS Fallback for Connectivity Issues Using dnsMode Settings

> Learn how Motrix handles DNS fallback for connectivity issues with its dnsMode settings. Discover auto, system, and engine modes for reliable downloads.

- Repository: [Dr_rOot/Motrix](https://github.com/agalwood/Motrix)
- Tags: how-to-guide
- Published: 2026-08-19

---

**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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/src/core/engine/aria2/dns-fallback.ts) (lines 24-31). The `dnsModeToAsyncDns()` function translates the `DnsResolutionMode` enum into a boolean value:

```ts
// 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`](https://github.com/agalwood/Motrix/blob/main/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:

```ts
// 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`](https://github.com/agalwood/Motrix/blob/main/src/core/engine/aria2/dns-fallback.ts) (lines 17-22) examines error messages using regex matching against standard c-ares error codes:

```ts
// 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`](https://github.com/agalwood/Motrix/blob/main/src/main/ipc/commands.ts) (lines 150-155) and [`src/server/ipc/commands.ts`](https://github.com/agalwood/Motrix/blob/main/src/server/ipc/commands.ts) (lines 66-71), the IPC command handlers detect `dnsMode` changes and reset the internal state:

```ts
// 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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/src/main/ipc/commands.ts) and [`src/server/ipc/commands.ts`](https://github.com/agalwood/Motrix/blob/main/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.