XTLS/Xray-core · error

UdpIdleTimeout must be between 2 and 600

Error message

UdpIdleTimeout must be between 2 and 600

What it means

Thrown by HysteriaConfig.Build() when udpIdleTimeout is non-zero and outside the 2-600 second window. Zero means 'use the default' and is allowed; any explicit value must be at least 2 seconds (below that, UDP sessions flap) and at most 600 seconds (above that, dead NAT mappings cause silent loss).

Source

Thrown at infra/conf/transport_method.go:784

	Up         *Bandwidth `json:"up"`
	Down       *Bandwidth `json:"down"`
	UdpHop     *UdpHop    `json:"udphop"`

	UdpIdleTimeout int64      `json:"udpIdleTimeout"`
	Masquerade     Masquerade `json:"masquerade"`
}

func (c *HysteriaConfig) Build() (proto.Message, error) {
	if c.Version != 2 {
		return nil, errors.New("version != 2")
	}

	if c.Congestion != nil || c.Up != nil || c.Down != nil || c.UdpHop != nil {
		errors.LogWarning(context.Background(), "congestion & up & down & udphop move to finalmask/quicParams")
	}

	if c.UdpIdleTimeout != 0 && (c.UdpIdleTimeout < 2 || c.UdpIdleTimeout > 600) {
		return nil, errors.New("UdpIdleTimeout must be between 2 and 600")
	}

	config := &hysteria.Config{}
	config.Auth = c.Auth
	config.UdpIdleTimeout = c.UdpIdleTimeout
	config.MasqType = c.Masquerade.Type
	config.MasqFile = c.Masquerade.Dir
	config.MasqUrl = c.Masquerade.Url
	config.MasqUrlRewriteHost = c.Masquerade.RewriteHost
	config.MasqUrlInsecure = c.Masquerade.Insecure
	config.MasqString = c.Masquerade.Content
	config.MasqStringHeaders = c.Masquerade.Headers
	config.MasqStringStatusCode = c.Masquerade.StatusCode

	if config.UdpIdleTimeout == 0 {
		config.UdpIdleTimeout = 60
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Set udpIdleTimeout to a value between 2 and 600 (seconds).
2. Omit the field (or set 0) to use the default.

Example fix

// before
"udpIdleTimeout": 30000
// after
"udpIdleTimeout": 60

if h.UdpIdleTimeout != 0 && (h.UdpIdleTimeout < 2 || h.UdpIdleTimeout > 600) {
    return fmt.Errorf("udpIdleTimeout %d outside 2-600 seconds", h.UdpIdleTimeout)
}

When it happens

Trigger: Setting "udpIdleTimeout": 1 or "udpIdleTimeout": 900 in the hysteria block.

Common situations: Trying to expire UDP sessions aggressively for NAT rebinding, or copying a NAT keepalive value in milliseconds (e.g. 30000) instead of seconds.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Failed to build Hysteria config.
• MaxIdleTimeout must be between 4 and 120
• unsupported unit:
• version != 2
• bridge tag is empty

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