{"record":{"id":"d29ba49c6b0c4752","repo":"denoland/deno","slug":"bindingname-errcodemessage-name","errorCode":null,"errorMessage":"${bindingName} ${errCodeMessage} ${name}","messagePattern":"\\$\\{bindingName\\} \\$\\{errCodeMessage\\} \\$\\{name\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"ext/node/polyfills/dns.ts","lineNumber":435,"sourceCode":"    if (isResolveCallback(options)) {\n      callback = options;\n      options = {};\n    }\n\n    validateString(name, \"name\");\n    validateFunction(callback, \"callback\");\n\n    const req = new QueryReqWrap();\n    req.bindingName = bindingName;\n    req.callback = callback as ResolveCallback;\n    req.hostname = name;\n    req.oncomplete = onresolve;\n    req.ttl = !!(options && (options as ResolveOptions).ttl);\n\n    const err = this._handle[bindingName](req, toASCII(name));\n\n    if (err) {\n      throw dnsException(err, bindingName, name);\n    }\n\n    return req;\n  }\n\n  ObjectDefineProperty(query, \"name\", {\n    __proto__: null,\n    value: bindingName,\n  });\n\n  return query;\n}\n\nconst resolveMap = ObjectCreate(null);\n\nclass Resolver extends CallbackResolver {\n  constructor(options?: ResolverOptions) {\n    super(options);","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/denoland/deno/blob/a961cdec3b1948844414ebeecc697dcad76df2d1/ext/node/polyfills/dns.ts#L417-L453","documentation":"dns.promises/resolve query() calls the native c-ares binding via this._handle[bindingName](req, toASCII(name)). If the binding returns a nonzero error code, dnsException(err, bindingName, name) builds and throws a Node-style DNS error whose message includes the binding name, the error code/message (e.g. ENOTFOUND, ESERVFAIL) and the queried name.","triggerScenarios":"dns.resolve*/dns.promises.resolve* failing synchronously at the c-ares layer — e.g. NXDOMAIN for an unknown name, SERVFAIL/timeout from resolvers, malformed internationalized names after toASCII punycode conversion, or no configured nameservers.","commonSituations":"Resolving a hostname that doesn't exist; DNS server outages or blocked UDP/53 in containers; resolv.conf misconfiguration; IDN names that fail punycode conversion.","solutions":["Catch the error and inspect err.code (ENOTFOUND/ESERVFAIL/ECONNREFUSED) to decide between fixing the name and retrying with fallback resolvers.","Retry with a public resolver via a dns.Resolver({ servers: ['8.8.8.8'] }) when the system resolver is broken.","Verify the hostname spelling and that it is a name (not an IP) — resolve* APIs require hostnames; use dns.lookup for literals.","Check /etc/resolv.conf and network/VPN settings if all queries fail."],"exampleFix":"// before\nconst addrs = await dns.promises.resolve4('unknown.example'); // throws ENOTFOUND\n// after\ntry {\n  const addrs = await dns.promises.resolve4('unknown.example');\n} catch (err) {\n  if (err.code === 'ENOTFOUND') {\n    const resolver = new dns.promises.Resolver({ servers: ['8.8.8.8'] });\n    return resolver.resolve4('unknown.example');\n  }\n  throw err;\n}","handlingStrategy":"try-catch","validationCode":"function assertResolvableName(name) {\n  if (!name || typeof name !== 'string') throw new TypeError('hostname required');\n  if (/^\\d{1,3}(\\.\\d{1,3}){3}$/.test(name)) {\n    throw new TypeError('use dns.lookup for IP literals, not dns.resolve*');\n  }\n  toASCII(name); // throws early on malformed IDN\n}","typeGuard":"function isHostname(name) {\n  return typeof name === 'string' && name.length > 0 && !net.isIP(name);\n}","tryCatchPattern":"try {\n  return await dns.promises.resolve4(name);\n} catch (err) {\n  if (err.code === 'ENOTFOUND') return []; // name does not exist\n  if (['ESERVFAIL', 'ETIMEOUT', 'ECONNREFUSED'].includes(err.code)) {\n    // retry with fallback resolver\n    const r = new dns.promises.Resolver({ servers: ['8.8.8.8', '1.1.1.1'] });\n    return r.resolve4(name);\n  }\n  throw err;\n}","preventionTips":["Always inspect err.code to distinguish 'name doesn't exist' from 'resolver unreachable'.","Configure a fallback Resolver with public nameservers for production lookups.","Convert IP literals with dns.lookup, not dns.resolve*.","Timeout-wrap lookups (Promise.race) so resolver outages fail fast."],"tags":["dns","network","node-compat"],"backgroundTag":"dns-lookup-failed","analyzedSha":"a961cdec3b1948844414ebeecc697dcad76df2d1","analyzedAt":"2026-09-03T14:18:07.398Z","contentChangedAt":"2026-09-03T14:18:07.398Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}