XTLS/Xray-core · error
gecko: invalid min/max packet size
Error message
gecko: invalid min/max packet size
What it means
Thrown by Salamander.Build() (a 'gecko' transport config) when a packetSize range is present but invalid: the config requires 0 < from <= to <= 2048. It uses a custom errors.New that concatenates the message with context. The check only applies when PacketSize.To > 0; if To is 0 the range is omitted entirely and the plain gecko Config is emitted.
Source
Thrown at infra/conf/transport_finalmask.go:638
return &header.Config{ID: 3}, nil
case "wechat":
return &header.Config{ID: 4}, nil
case "wireguard":
return &header.Config{ID: 5}, nil
default:
return nil, errors.New("invalid header ", c.Header)
}
}
type Salamander struct {
Password string `json:"password"`
PacketSize Int32Range `json:"packetSize"`
}
func (c *Salamander) Build() (proto.Message, error) {
if c.PacketSize.To > 0 {
if c.PacketSize.From <= 0 || c.PacketSize.To > 2048 {
return nil, errors.New("gecko: invalid min/max packet size")
}
return &salamander.GeckoConfig{
Password: c.Password,
MinPacketSize: c.PacketSize.From,
MaxPacketSize: c.PacketSize.To,
}, nil
}
return &salamander.Config{
Password: c.Password,
}, nil
}
type Sudoku struct {
Password string `json:"password"`
ASCII string `json:"ascii"`
CustomTable string `json:"customTable"`
LegacyCustomTable string `json:"custom_table"`View on GitHub (pinned to 7d214f8b09)
Solutions
- Set packetSize.From to a positive value (e.g. 1) whenever To is set.
- Cap packetSize.To at 2048 or below.
- If you do not need a packet-size range, omit packetSize (or set To to 0) so the plain gecko Config is built.
Example fix
// before
"packetSize": { "from": 0, "to": 1500 }
// after
"packetSize": { "from": 1, "to": 1024 } Defensive patterns
Strategy: validation
Validate before calling
func validPacketSize(from, to int32) bool {
if to <= 0 {
return true // range omitted
}
return from > 0 && to <= 2048 && from <= to
} Prevention
- Treat 2048 as a hard ceiling when generating salamander packet sizes.
- Always emit both from and to together, never a bare max with min=0.
- Run JSON config through a JSON-schema or pre-flight validator before loading.
When it happens
Trigger: Setting json packetSize like {"from": 0, "to": 1024} (From <= 0) or {"from": 1, "to": 4096} (To > 2048) on a salamander/gecko outbound triggers it. Any config where To > 0 while From <= 0, or To exceeding the hard 2048 ceiling, fails at config-build time.
Common situations: Copy-pasting MTU-like values (e.g. 1500 or 9000) from other transports into packetSize; setting only the max and leaving min at 0; confusing the 2048 hard limit with a larger L1/L2 packet size.
Related errors
- invalid scheme + u.Scheme
- empty stunServers
- Config: unknown transport protocol: + p
- bridge tag is empty
- bridge domain is empty
AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15).
Data as JSON: /api/errors/7b997c258bfbe002.
Report an issue: GitHub.