XTLS/Xray-core · critical · errors.Error

failed to get server spec

Error message

failed to get server spec

What it means

protocol.NewServerSpecFromPB failed to convert the protobuf server entry into an internal server spec. This validates address/port/user fields of the configured HTTP proxy server; malformed address, invalid port, or bad user credentials shape are the usual causes. The parse error is chained via .Base(err).

Source

Thrown at proxy/http/client.go:57

type h2Conn struct {
	rawConn net.Conn
	h2Conn  *http2.ClientConn
}

var (
	cachedH2Mutex sync.Mutex
	cachedH2Conns map[net.Destination]h2Conn
)

// NewClient create a new http client based on the given config.
func NewClient(ctx context.Context, config *ClientConfig) (*Client, error) {
	if config.Server == nil {
		return nil, errors.New(`no target server found`)
	}
	server, err := protocol.NewServerSpecFromPB(config.Server)
	if err != nil {
		return nil, errors.New("failed to get server spec").Base(err)
	}

	v := core.MustFromContext(ctx)
	return &Client{
		server:        server,
		policyManager: v.GetFeature(policy.ManagerType()).(policy.Manager),
		header:        config.Header,
	}, nil
}

// Process implements proxy.Outbound.Process. We first create a socket tunnel via HTTP CONNECT method, then redirect all inbound traffic to that tunnel.
func (c *Client) Process(ctx context.Context, link *transport.Link, dialer internet.Dialer) error {
	outbounds := session.OutboundsFromContext(ctx)
	ob := outbounds[len(outbounds)-1]
	if !ob.Target.IsValid() {
		return errors.New("target not specified.")
	}
	ob.Name = "http"

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Read the Base error — it names the invalid field
2. Ensure address is a valid host/IP and port is an integer in 1-65535
3. For authenticated proxies keep users entries to {"user","pass"}; remove protocol-specific fields that don't apply to HTTP
4. Validate with `xray run -test -c config.json`

```go
if _, err := protocol.NewServerSpecFromPB(cfg.Server); err != nil {
    // fix address/port/users before constructing the outbound
}
```

When it happens

Trigger: settings.servers[0] contains an invalid address (empty string, bad host), port 0/out-of-range, or a users entry with an unsupported encryption/credential format for the HTTP outbound.

Common situations: Copy-pasted server entry from a SOCKS example into an HTTP outbound, port typed as string in hand-written JSON, leftover cipher fields from older configs.

Related errors

• no target server found
• failed to get outbound handler with tag: ${tag}
• existing tag found: ${tag}
• bridge tag is empty
• bridge domain is empty

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