XTLS/Xray-core · error

failed to build nameserver

Error message

failed to build nameserver

What it means

Wrapper error from dns Config Build in infra/conf/dns.go: one of the dns.servers entries failed NameServerConfig.Build (address missing, bad clientIp, invalid expected-IP rules, geodata parse failure). The underlying error is chained with .Base(err), so the real cause is one level down in the error chain.

Source

Thrown at infra/conf/dns.go:357

		writeList("expected", nsc.ExpectedIPs)
		writeList("expect", nsc.ExpectIPs)
		writeList("unexpected", nsc.UnexpectedIPs)

		key := sb.String()

		if id, ok := policyMap[key]; ok {
			return id
		}
		id := nextPolicyID
		nextPolicyID++
		policyMap[key] = id
		return id
	}

	for _, server := range c.Servers {
		ns, err := server.Build()
		if err != nil {
			return nil, errors.New("failed to build nameserver").Base(err)
		}
		ns.PolicyID = buildPolicyID(server)
		config.NameServer = append(config.NameServer, ns)
	}

	if c.Hosts != nil {
		staticHosts, err := c.Hosts.Build()
		if err != nil {
			return nil, errors.New("failed to build hosts").Base(err)
		}
		config.StaticHosts = append(config.StaticHosts, staticHosts...)
	}
	if c.UseSystemHosts {
		systemHosts, err := readSystemHosts()
		if err != nil {
			return nil, errors.New("failed to read system hosts").Base(err)
		}
		config.StaticHosts = append(config.StaticHosts, systemHosts...)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Inspect the chained base error to identify which server entry and which check failed
2. Fix that entry per the underlying error (add address, fix clientIp, correct geodata rules)
3. Bisect the servers array by commenting out entries to locate the offender quickly

for i, server := range dnsCfg.Servers {
    if _, err := server.Build(); err != nil {
        return fmt.Errorf("dns.servers[%d] invalid: %w", i, err)
    }
}

if _, err := dnsConf.Build(); err != nil {
    var baseErr = err
    for errors.Unwrap(baseErr) != nil {
        baseErr = errors.Unwrap(baseErr) // descend to the real per-server cause
    }
    return fmt.Errorf("DNS build failed at servers entry, root cause: %v", baseErr)
}

When it happens

Trigger: Any per-server Build failure inside the servers loop: errors 252 (no address) or 253 (clientIp not IP) are the typical bases; invalid geodata rule strings in 'domains'/'expectedIPs' also land here.

Common situations: One bad entry in an otherwise long servers array; after upgrading Xray the geodata rule syntax changed and an old entry no longer parses.

Related errors

• failed to build hosts
• failed to parse name server: {}
• nameserver address is not specified
• not an IP address:{}
• invalid address

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/41c69ba1e76a5b4d. Report an issue: GitHub.