XTLS/Xray-core · error

cannot understand address

Error message

cannot understand address

What it means

The geodata downloader's custom HTTP dialer joins network and address into one string and passes it to net.ParseDestination; if that parse fails the destination is un-understandable and dialing cannot proceed. It wraps the underlying parse error with .Base(err).

Source

Thrown at app/geodata/download.go:75

func newDownloader(ctx context.Context, dispatcher routing.Dispatcher, outbound string) *downloader {
	return &downloader{
		ctx:         ctx,
		httpClient:  newClient(ctx, dispatcher, outbound, false),
		httpsClient: newClient(ctx, dispatcher, outbound, true),
	}
}

func newClient(baseCtx context.Context, dispatcher routing.Dispatcher, outbound string, isHTTPS bool) *http.Client {
	dial := func(ctx context.Context, network, address string) (net.Conn, error) {
		var conn net.Conn
		err := task.Run(ctx, func() error {
			if tagged.Dialer == nil {
				return errors.New("tagged dialer is not initialized")
			}
			dest, err := net.ParseDestination(network + ":" + address)
			if err != nil {
				return errors.New("cannot understand address").Base(err)
			}
			c, err := tagged.Dialer(baseCtx, dispatcher, dest, outbound)
			if err != nil {
				return errors.New("cannot dial remote address ", dest).Base(err)
			}
			conn = c
			return nil
		})
		if err != nil {
			return nil, errors.New("cannot finish connection").Base(err)
		}
		return &idleConn{
			Conn: conn,
		}, nil
	}
	if isHTTPS {
		return &http.Client{
			Transport: &http2.Transport{

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Verify the geodata asset URLs in config are fully qualified, e.g. https://raw.githubusercontent.com/.../geosite.dat
2. Print the underlying Base error to see exactly which string failed to parse, then fix the URL that produced it
3. Check that no outbound/tagged dialer middleware is rewriting the destination address

// Validate asset URLs before handing them to the downloader:
u, err := url.Parse(assetURL)
if err != nil || u.Host == "" {
    return fmt.Errorf("invalid geodata asset URL: %s", assetURL)
}

When it happens

Trigger: http.Client invokes DialContext with an address that is not host:port (or a network scheme net.ParseDestination rejects), e.g. a URL whose authority lacks a port while using the plain http branch, or an address with unexpected formatting.

Common situations: Misconfigured geodata asset URL (e.g. 'geosite.dat' without scheme/host parsed into a bogus address); unusual proxy environment rewriting addresses; a bug in whatever constructed the request URL.

Related errors

• connection idle timeout
• cannot dial remote address
• cannot finish connection
• redirected to non-https URL:
• stopped after 10 redirects

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