{"record":{"id":"574589e587edc0b9","repo":"XTLS/Xray-core","slug":"invalid-metalen","errorCode":null,"errorMessage":"invalid metalen ","messagePattern":"invalid metalen ","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"common/mux/frame.go","lineNumber":120,"sourceCode":"\t\t}\n\t} else if b.UDP != nil {\n\t\tb.WriteByte(byte(TargetNetworkUDP))\n\t\taddrParser.WriteAddressPort(b, b.UDP.Address, b.UDP.Port)\n\t}\n\n\tlen1 := b.Len()\n\tbinary.BigEndian.PutUint16(lenBytes, uint16(len1-len0))\n\treturn nil\n}\n\n// Unmarshal reads FrameMetadata from the given reader.\nfunc (f *FrameMetadata) Unmarshal(reader io.Reader, readSourceAndLocal bool) error {\n\tmetaLen, err := serial.ReadUint16(reader)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif metaLen > 512 {\n\t\treturn errors.New(\"invalid metalen \", metaLen).AtError()\n\t}\n\n\tb := buf.New()\n\tdefer b.Release()\n\n\tif _, err := b.ReadFullFrom(reader, int32(metaLen)); err != nil {\n\t\treturn err\n\t}\n\treturn f.UnmarshalFromBuffer(b, readSourceAndLocal)\n}\n\n// UnmarshalFromBuffer reads a FrameMetadata from the given buffer.\n// Visible for testing only.\nfunc (f *FrameMetadata) UnmarshalFromBuffer(b *buf.Buffer, readSourceAndLocal bool) error {\n\tif b.Len() < 4 {\n\t\treturn errors.New(\"insufficient buffer: \", b.Len())\n\t}\n","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/mux/frame.go#L102-L138","documentation":"FrameMetadata.Unmarshal reads a uint16 meta length from the mux stream and rejects anything over 512 bytes — well-formed mux frame metadata is always far smaller. A larger value means the stream is desynchronized or the peer is speaking a different protocol, so parsing aborts before allocating the buffer.","triggerScenarios":"Connecting a mux-enabled outbound to a server that does not support mux (or vice versa), causing arbitrary bytes to be read as a frame header; stream corruption after a partial write; version mismatch in frame format.","commonSituations":"See trigger scenarios.","solutions":["Ensure mux is enabled on both ends of the tunnel (client outbound and server inbound handling).","Disable mux on the outbound to confirm the underlying proxy works; re-enable once verified.","Align client/server Xray versions to avoid frame format differences."],"exampleFix":"// before\noutbound: { \"mux\": {\"enabled\": true}, \"protocol\": \"vless\", ... } // server lacks mux support\n\n// after\noutbound: { \"mux\": {\"enabled\": false}, \"protocol\": \"vless\", ... }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := frame.Unmarshal(reader, false); err != nil {\n    if strings.Contains(err.Error(), \"invalid metalen\") {\n        return errors.New(\"mux stream desynchronized: peer likely not mux-capable\").Base(err)\n    }\n    return err\n}","preventionTips":["Enable mux only where the server inbound is known to support it (same core family).","Pin compatible client/server versions; test mux handshake after each upgrade.","Treat any metalen failure as fatal for the connection — never reuse the stream."],"tags":["mux","protocol","framing","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}