docmirror/dev-sidecar · warning

域名 ${hostname} 的DNS配置有误，未配置dnsName，配置值：

Error message

域名 ${hostname} 的DNS配置有误，未配置dnsName，配置值：

What it means

During server startup, options.js validates each entry of dns.mapping. When an entry is an object (not a plain string), it must contain a dnsName property pointing at the DNS provider to use; if dnsName is null/undefined, the library logs this warning and deletes the hostname from the mapping, so the domain falls back to normal DNS resolution instead of the intended provider. This is a config-shape validation warning, not a thrown exception.

Source

Thrown at packages/mitmproxy/src/options.js:59

  return ret
}

function handleDnsMapping (dnsMapping, familyMapping) {
  // 循环读取所有key value
  for (const hostname in dnsMapping) {
    const value = dnsMapping[hostname]
    if (value == null) {
      delete dnsMapping[hostname]
      continue
    }

    if (typeof value === 'string') {
      dnsMapping[hostname] = {
        dnsName: value,
        family: Number.parseInt(familyMapping[hostname]) === 6 ? 6 : 4,
      }
    } else if (value.dnsName == null) {
      log.warn(`域名 ${hostname} 的DNS配置有误，未配置dnsName，配置值：`, value)
      delete dnsMapping[hostname]
    }
  }

  return dnsMapping
}

module.exports = (serverConfig) => {
  const intercepts = matchUtil.domainMapRegexply(buildIntercepts(serverConfig.intercepts))
  const whiteList = matchUtil.domainMapRegexply(serverConfig.whiteList)
  const timeoutMapping = matchUtil.domainMapRegexply(serverConfig.setting.timeoutMapping)

  const dnsMapping = handleDnsMapping(serverConfig.dns.mapping, serverConfig.dns.familyMapping || {})
  const setting = serverConfig.setting

  if (!setting.script.dirAbsolutePath) {
    setting.script.dirAbsolutePath = path.join(setting.rootDir, setting.script.defaultDir)
  }

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Add the required dnsName key to the mapping entry, naming a configured DNS provider, e.g. `{ dnsName: 'alidns', family: 4 }`.
2. Alternatively use the simple string form: `'github.com': 'alidns'`, which handleDnsMapping converts to `{ dnsName: 'alidns', family: 4 }` automatically.
3. Verify the referenced provider actually exists in `dns.providers` in your config, otherwise resolution for that hostname will still fail.
4. Check ~/.dev-sidecar/config.json for the offending entry and remove or fix it; the entry is deleted at runtime so the domain silently uses default DNS until fixed.

Example fix

// before
{
  "dns": {
    "mapping": {
      "api.github.com": { "provider": "alidns", "family": 4 }
    }
  }
}
// after
{
  "dns": {
    "mapping": {
      "api.github.com": { "dnsName": "alidns", "family": 4 }
    }
  }
}

function validateDnsMapping (mapping) {
  if (!mapping) return []
  return Object.entries(mapping)
    .filter(([host, v]) => v != null && typeof v !== 'string' && (v.dnsName == null))
    .map(([host]) => host)
}

const bad = validateDnsMapping(config.dns.mapping)
if (bad.length > 0) {
  throw new Error(`dns.mapping entries missing dnsName: ${bad.join(', ')}`)
}

function hasDnsName (entry) {
  return typeof entry === 'string' || (entry != null && typeof entry === 'object' && typeof entry.dnsName === 'string' && entry.dnsName.length > 0)
}

When it happens

Trigger: Passing serverConfig.dns.mapping entries as objects like `{ 'github.com': { provider: 'alidns' } }` or `{ 'x.com': {} }` (missing dnsName), typically after copying a config example or hand-editing ~/.dev-sidecar/config.json where the object form was expected to carry dnsName.

Common situations: Users upgrading dev-sidecar who renamed fields (e.g. using 'provider' or 'server' instead of 'dnsName'); JSON5 config edits where dnsName was accidentally deleted; programmatically building a mapping that merges multiple sources and drops dnsName; GUI config import/export losing the dnsName key.

Related errors

• Unknown type DNS: ${server}, provider: ${provider}
• At least host, servername and name must be set.
• IPv6 地址 ${ip} 多次不可达（ENETUNREACH），已自动禁用 IPv6 DNS 解析
• [DNS-over-${this.dnsType}
• 域名 ${rOptions.hostname} 在dns中未配置，但使用了 sni: ${rOptions.server

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