{"record":{"id":"8efbff348dc8d9e5","repo":"docmirror/dev-sidecar","slug":"hostname-dns-dnsname","errorCode":null,"errorMessage":"域名 ${hostname} 的DNS配置有误，未配置dnsName，配置值：","messagePattern":"域名 (.+?) 的DNS配置有误，未配置dnsName，配置值：","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/mitmproxy/src/options.js","lineNumber":59,"sourceCode":"  return ret\n}\n\nfunction handleDnsMapping (dnsMapping, familyMapping) {\n  // 循环读取所有key value\n  for (const hostname in dnsMapping) {\n    const value = dnsMapping[hostname]\n    if (value == null) {\n      delete dnsMapping[hostname]\n      continue\n    }\n\n    if (typeof value === 'string') {\n      dnsMapping[hostname] = {\n        dnsName: value,\n        family: Number.parseInt(familyMapping[hostname]) === 6 ? 6 : 4,\n      }\n    } else if (value.dnsName == null) {\n      log.warn(`域名 ${hostname} 的DNS配置有误，未配置dnsName，配置值：`, value)\n      delete dnsMapping[hostname]\n    }\n  }\n\n  return dnsMapping\n}\n\nmodule.exports = (serverConfig) => {\n  const intercepts = matchUtil.domainMapRegexply(buildIntercepts(serverConfig.intercepts))\n  const whiteList = matchUtil.domainMapRegexply(serverConfig.whiteList)\n  const timeoutMapping = matchUtil.domainMapRegexply(serverConfig.setting.timeoutMapping)\n\n  const dnsMapping = handleDnsMapping(serverConfig.dns.mapping, serverConfig.dns.familyMapping || {})\n  const setting = serverConfig.setting\n\n  if (!setting.script.dirAbsolutePath) {\n    setting.script.dirAbsolutePath = path.join(setting.rootDir, setting.script.defaultDir)\n  }","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/docmirror/dev-sidecar/blob/7710cd56cce760c708f30b01d2d4056eb8c402d5/packages/mitmproxy/src/options.js#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the required dnsName key to the mapping entry, naming a configured DNS provider, e.g. `{ dnsName: 'alidns', family: 4 }`.","Alternatively use the simple string form: `'github.com': 'alidns'`, which handleDnsMapping converts to `{ dnsName: 'alidns', family: 4 }` automatically.","Verify the referenced provider actually exists in `dns.providers` in your config, otherwise resolution for that hostname will still fail.","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."],"exampleFix":"// before\n{\n  \"dns\": {\n    \"mapping\": {\n      \"api.github.com\": { \"provider\": \"alidns\", \"family\": 4 }\n    }\n  }\n}\n// after\n{\n  \"dns\": {\n    \"mapping\": {\n      \"api.github.com\": { \"dnsName\": \"alidns\", \"family\": 4 }\n    }\n  }\n}","handlingStrategy":"validation","validationCode":"function validateDnsMapping (mapping) {\n  if (!mapping) return []\n  return Object.entries(mapping)\n    .filter(([host, v]) => v != null && typeof v !== 'string' && (v.dnsName == null))\n    .map(([host]) => host)\n}\n\nconst bad = validateDnsMapping(config.dns.mapping)\nif (bad.length > 0) {\n  throw new Error(`dns.mapping entries missing dnsName: ${bad.join(', ')}`)\n}","typeGuard":"function hasDnsName (entry) {\n  return typeof entry === 'string' || (entry != null && typeof entry === 'object' && typeof entry.dnsName === 'string' && entry.dnsName.length > 0)\n}","tryCatchPattern":null,"preventionTips":["Always include dnsName in object-form dns.mapping entries; prefer the shorthand string form ('host': 'providerName') when no custom family is needed.","Keep DNS provider names in dns.mapping consistent with keys defined under dns.providers.","After editing ~/.dev-sidecar/config.json, grep for mapping entries lacking dnsName before restarting.","Watch the core log for this warning at startup — the entry is silently dropped, so verify the domain still resolves as expected."],"tags":["dns","config-validation","mitmproxy"],"backgroundTag":"missing-dnsname-config","analyzedSha":"7710cd56cce760c708f30b01d2d4056eb8c402d5","analyzedAt":"2026-08-31T22:07:07.234Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}