docmirror/dev-sidecar · warning

IPv6 地址 ${ip} 多次不可达（ENETUNREACH），已自动禁用 IPv6 DNS 解析

Error message

IPv6 地址 ${ip} 多次不可达（ENETUNREACH），已自动禁用 IPv6 DNS 解析

What it means

The DNS subsystem tracks failures to reach IPv6 addresses. After 3 reported IPv6 errors (typically ENETUNREACH from connect attempts), the module sets a module-level flag `ipv6Unavailable = true` and permanently stops selecting IPv6 DNS addresses for the lifetime of the process, logging this warning once.

Source

Thrown at packages/mitmproxy/src/lib/dns/base.js:30

  for (const name of Object.keys(nets)) {
    for (const info of nets[name]) {
      if (!info.internal && info.family === 'IPv6' && !info.address.startsWith('fe80:')) {
        return false
      }
    }
  }
  log.info('未检测到可用的 IPv6 网络接口，将过滤所有 IPv6 DNS 解析结果')
  return true
})()

// 运行时兜底：累计 3 次 IPv6 ENETUNREACH 后，认为上游 IPv6 不可达
let ipv6ErrCount = 0
function reportIPv6Error (ip) {
  if (!isIPv6(ip) || ipv6Unavailable) return
  ipv6ErrCount++
  if (ipv6ErrCount >= 3) {
    ipv6Unavailable = true
    log.warn(`IPv6 地址 ${ip} 多次不可达（ENETUNREACH），已自动禁用 IPv6 DNS 解析`)
  }
}
module.exports.reportIPv6Error = reportIPv6Error

function mapToList (ipMap) {
  const ipList = []
  for (const key in ipMap) {
    const value = ipMap[key]
    if (value && value !== 'false' && value !== '0') { // 配置为 ture 时才生效
      ipList.push(key)
    }
  }
  return ipList
}

const defaultCacheSize = 1024

class IpCache extends DynamicChoice {

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Remove IPv6 addresses (AAAA entries) from the DNS pre-set ip lists in config so only IPv4 servers are tried.
2. Enable IPv6 connectivity on the host/network, or accept the auto-disable (it is the intended mitigation and speeds up lookups).
3. Restart the proxy process after fixing IPv6 connectivity — the `ipv6Unavailable` flag is not reset at runtime.

Example fix

// before (config)
"dnsMap": { "aliyun": { "ips": ["2400:3200::1", "223.5.5.5"] } }
// after
"dnsMap": { "aliyun": { "ips": ["223.5.5.5"] } }

const ips = dnsConfig?.ips || []
if (ips.some(ip => ip.includes(':'))) console.warn('IPv6 entries present; disable them if host has no IPv6 route')

const isIPv6 = (s) => typeof s === 'string' && /^[0-9a-fA-F:]+$/.test(s) && s.includes(':')

When it happens

Trigger: Any DNS lookup path calling reportIPv6Error(ip) from onFree/connect failover when a preset or resolved AAAA address fails with ENETUNREACH three times, on a host/stack with no working IPv6 route.

Common situations: Machines or VPNs with IPv6 disabled at the kernel or router level while DNS config (e.g. pre-set ip lists) still contains AAAA addresses; Docker default bridge (no IPv6); corporate networks without IPv6.

Related errors

• Unknown type DNS: ${server}, provider: ${provider}
• At least host, servername and name must be set.
• [speed] test error: ${this.hostname} ➜ ${item.host}:${this
• [speed] test by TCP error:
• 下载远程配置成功，但内容为空:

AI-assisted analysis of docmirror/dev-sidecar@7710cd56cc (2026-08-31). Data as JSON: /api/errors/344db1b3c59f3409. Report an issue: GitHub.