docmirror/dev-sidecar · error

At least host, servername and name must be set.

Error message

At least host, servername and name must be set.

What it means

The DNS-over-TLS query function validates its options before opening the TLS socket: host (server IP), servername (SNI for the TLS handshake) and name (the record to resolve) are all mandatory. Because the promise executor throws synchronously, the error surfaces as an uncaught exception rather than a rejected promise, so it typically crashes the calling context. It guards against constructing a DoT request that could not possibly complete.

Source

Thrown at packages/mitmproxy/src/lib/dns/util/dns-over-tls.js:22

const dnsPacket = require('dns-packet')
const tls_1 = require('node:tls')
const randi = require('random-int')

const TWO_BYTES = 2

function getDnsQuery ({ type, name, klass, id }) {
  return {
    id,
    type: 'query',
    flags: dnsPacket.RECURSION_DESIRED,
    questions: [{ class: klass, name, type }],
  }
}

function query ({ host, servername, type, name, klass, port, family, rejectUnauthorized, timeout }) {
  return new Promise((resolve, reject) => {
    if (!host || !servername || !name) {
      throw new Error('At least host, servername and name must be set.')
    }

    let response = Buffer.alloc(0)
    let packetLength = 0
    const dnsQuery = getDnsQuery({ id: randi(0x0, 0xFFFF), type, name, klass })
    const dnsQueryBuf = dnsPacket.streamEncode(dnsQuery)
    const socket = tls_1.connect({ host, port, servername, family: Number.parseInt(family) === 6 ? 6 : 4, rejectUnauthorized, timeout })

    // 超时处理
    let isFinished = false
    let interval
    if (timeout > 0) {
      interval = setInterval(() => {
        if (!isFinished) {
          socket.destroy((...args) => {
            console.info('socket destory callback args:', args)
          })

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Check the DNS provider config for the failing server: ensure it resolves to a concrete IP so host and servername are both set
2. Ensure the queried domain 'name' is a non-empty hostname (not an empty string or undefined)
3. If calling query() directly, pass { host, servername, name } explicitly: host = resolver IP, servername = TLS SNI hostname, name = domain to look up
4. Wrap the call in try/catch (the throw is synchronous inside the promise executor) or prefer the higher-level dns/index.js lookup which fills these fields

Example fix

// before
await dotQuery({ host: resolverIp, name: 'example.com' })
// after
await dotQuery({ host: resolverIp, servername: 'dns.example.com', name: 'example.com' })

function canDoTQuery(opts) {
  return Boolean(opts && opts.host && opts.servername && opts.name)
}
if (!canDoTQuery(opts)) throw new Error('DoT query needs host, servername and name')

function isDotQueryOptions(o) {
  return o != null && typeof o.host === 'string' && o.host.length > 0 &&
    typeof o.servername === 'string' && o.servername.length > 0 &&
    typeof o.name === 'string' && o.name.length > 0
}

try {
  result = await dnsLookup(name, { type: 'tls' })
} catch (e) {
  if (String(e.message).includes('At least host, servername and name')) {
    // fall back to a UDP/https provider
    result = await dnsLookup(name, { type: 'https' })
  } else throw e
}

When it happens

Trigger: Calling query() (directly, or via a 'tls'/'dot' type DNS provider) with an options object missing host, servername, or name — e.g. a DNS provider config where the server IP could not be resolved (host missing) or where SNI servername was not derived.

Common situations: DoT provider configured with a hostname that failed its own pre-resolution so host/servername never got filled; programmatic use of dns-over-tls.js with a hand-built options object omitting fields; upstream resolver entry copied incompletely.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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

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