XTLS/Xray-core · error

nameserver address is not specified

Error message

nameserver address is not specified

What it means

Returned by NameServerConfig.Build in infra/conf/dns.go when the nameserver's Address is nil after unmarshaling. Every DNS server entry must yield an address (string form or object form 'address' key); if the advanced object parsed but carried no usable address, Build refuses to continue.

Source

Thrown at infra/conf/dns.go:86

		c.ExpectedIPs = advanced.ExpectedIPs
		c.ExpectIPs = advanced.ExpectIPs
		c.QueryStrategy = advanced.QueryStrategy
		c.Tag = advanced.Tag
		c.TimeoutMs = advanced.TimeoutMs
		c.DisableCache = advanced.DisableCache
		c.ServeStale = advanced.ServeStale
		c.ServeExpiredTTL = advanced.ServeExpiredTTL
		c.FinalQuery = advanced.FinalQuery
		c.UnexpectedIPs = advanced.UnexpectedIPs
		return nil
	}

	return errors.New("failed to parse name server: ", string(data))
}

func (c *NameServerConfig) Build() (*dns.NameServer, error) {
	if c.Address == nil {
		return nil, errors.New("nameserver address is not specified")
	}

	domainRules, err := geodata.ParseDomainRules(c.Domains, geodata.Domain_Substr)
	if err != nil {
		return nil, err
	}

	if len(c.ExpectedIPs) == 0 {
		c.ExpectedIPs = c.ExpectIPs
	}

	actPrior := false
	var newExpectedIPs StringList
	for _, s := range c.ExpectedIPs {
		if s == "*" {
			actPrior = true
		} else {
			newExpectedIPs = append(newExpectedIPs, s)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Add a string address to every dns.servers object entry
2. If generating configs programmatically, set NameServerConfig.Address (conf.Address) before Build
3. Validate each servers entry has an 'address' key before feeding the config to Xray

Example fix

// before
{"domains": ["geosite:cn"]}

// after
{"address": "223.5.5.5", "domains": ["geosite:cn"]}

func nameserverHasAddress(entry map[string]any) error {
    addr, ok := entry["address"]
    if !ok || addr == nil {
        return errors.New("nameserver entry has no address")
    }
    s, ok := addr.(string)
    if !ok || s == "" {
        return errors.New("nameserver address must be a non-empty string")
    }
    return nil
}

if _, err := nsc.Build(); err != nil {
    if strings.Contains(err.Error(), "nameserver address is not specified") {
        return fmt.Errorf("dns entry %v: add an 'address' field", nsc)
    }
    return err
}

When it happens

Trigger: {"address": ""} style entries that unmarshal but leave Address nil, or programmatic construction of NameServerConfig without setting Address before calling Build. String-form servers always set Address, so this mostly bites object form and API users.

Common situations: Third-party config generators emitting {"domains":[...]} without an address; runtime code building dns.Config from parsed JSON where an entry was skipped; upstream format changes moving the address key.

Related errors

• failed to parse name server: {}
• not an IP address:{}
• invalid address
• invalid DNS hosts
• unknown action: {}

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