XTLS/Xray-core · error · errors.Error

cannot understand address

Error message

cannot understand address

What it means

Thrown in app/observatory/observer.go:143 inside the HTTP transport's DialContext: net.ParseDestination failed to parse the 'network:addr' string built from Go's http package (e.g. 'tcp:www.google.com:443') into an Xray destination. This is an internal translation step between Go's dialer interface and Xray's net types, and failure means the address Xray derived was structurally invalid.

Source

Thrown at app/observatory/observer.go:143

		}
	}
	o.status = pruned
}

func (o *Observer) probe(outbound string) ProbeResult {
	errorCollectorForRequest := newErrorCollector()

	httpTransport := http.Transport{
		Proxy: func(*http.Request) (*url.URL, error) {
			return nil, nil
		},
		DialContext: func(ctx context.Context, network string, addr string) (net.Conn, error) {
			var connection net.Conn
			taskErr := task.Run(ctx, func() error {
				// MUST use Xray's built in context system
				dest, err := v2net.ParseDestination(network + ":" + addr)
				if err != nil {
					return errors.New("cannot understand address").Base(err)
				}
				trackedCtx := session.TrackedConnectionError(o.ctx, errorCollectorForRequest)
				conn, err := tagged.Dialer(trackedCtx, o.dispatcher, dest, outbound)
				if err != nil {
					return errors.New("cannot dial remote address ", dest).Base(err)
				}
				connection = conn
				return nil
			})
			if taskErr != nil {
				return nil, errors.New("cannot finish connection").Base(taskErr)
			}
			return connection, nil
		},
		TLSHandshakeTimeout: time.Second * 5,
	}
	httpClient := &http.Client{
		Transport: &httpTransport,

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check the observatory ProbeUrl string for typos — especially the port and scheme separator.
2. Verify you are on a recent xray-core version where ParseDestination handles the address forms your setup produces.
3. Test the URL with curl to confirm it yields a normal host:port.

// validate probe URL before use
if _, err := url.Parse(probeURL); err != nil {
    return fmt.Errorf("invalid probe URL %q: %w", probeURL, err)
}

When it happens

Trigger: The probe URL resolves to a form ParseDestination cannot handle — practically limited to exotic/unparseable host:port combinations or non-tcp networks; for normal hostnames and ports this never fires. It can also fire if the proxy layer rewrites the address to something malformed.

Common situations: Extremely rare in stock configs; appears when ProbeUrl has a malformed authority (bad port, stray characters) or when embedding code supplies a custom transport with unusual address formats.

Related errors

• underlying connection error
• failed to produce report
• cannot dial remote address
• cannot finish connection
• outbound failed to relay connection

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