{"record":{"id":"4a69089bfea0428d","repo":"actix/actix-web","slug":"invalid-control-frame-length-4a6908","errorCode":null,"errorMessage":"Invalid control frame length ({})","messagePattern":"Invalid control frame length \\((.+?)\\)","errorType":"validation","errorClass":"ProtocolError","httpStatus":null,"severity":"error","filePath":"actix-http/src/ws/mod.rs","lineNumber":48,"sourceCode":"    #[display(\"Received an unmasked frame from client\")]\n    UnmaskedFrame,\n\n    /// Received a masked frame from server.\n    #[display(\"Received a masked frame from server\")]\n    MaskedFrame,\n\n    /// Encountered invalid opcode.\n    #[display(\"Invalid opcode ({})\", _0)]\n    InvalidOpcode(#[error(not(source))] u8),\n\n    // TODO(semver-major):\n    // /// Received a frame with non-zero reserved bits.\n    // #[display(\"Received a frame with non-zero reserved bits\")]\n    // InvalidReservedBits,\n    //\n    /// Invalid control frame length\n    #[display(\"Invalid control frame length ({})\", _0)]\n    InvalidLength(#[error(not(source))] usize),\n\n    // TODO(semver-major): use in Parser::try_parse_close_payload\n    //\n    // /// Invalid close status code.\n    // #[display(\"Invalid close status code ({})\", _0)]\n    // InvalidCloseCode(#[error(not(source))] u16),\n    //\n    // /// Invalid UTF-8 close reason.\n    // #[display(\"Invalid UTF-8 close reason\")]\n    // InvalidCloseReason,\n    //\n    /// Bad opcode.\n    #[display(\"Bad opcode\")]\n    BadOpCode,\n\n    /// A payload reached size limit.\n    #[display(\"Payload reached size limit\")]\n    Overflow,","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/actix/actix-web/blob/c215607f4b6e9ba9accff4a949a33c98f218db20/actix-http/src/ws/mod.rs#L30-L66","documentation":"This is `ws::ProtocolError::InvalidLength(usize)` from actix-http's WebSocket module. RFC 6455 forbids control frames (ping, pong, close) from having a payload longer than 125 bytes, and actix-http's parser raises this error when a control frame exceeds that limit. It indicates the remote peer produced a spec-violating frame.","triggerScenarios":"Parser::parse encounters a control frame (opcode 0x8/0x9/0xA) whose payload length field is > 125 bytes.","commonSituations":"Interoperating with a custom WebSocket client that fragments or oversizes pings/pongs, a buggy library sending large close reasons without truncation, or a test harness generating oversized control frames.","solutions":["Fix the peer implementation to keep control frame payloads at 125 bytes or fewer (truncate close reasons/ping payloads).","On the actix side, keep `ws::Client`/ping payloads small; do not attach large data to ping frames.","Treat the error as a fatal protocol violation: close the connection with CloseCode::Protocol rather than attempting to continue.","If you control both ends, capture the reported length value to confirm the size rule that is being violated before patching the peer."],"exampleFix":"// before\nlet payload = reason.as_bytes(); // could exceed 125 bytes\nws.close(Some(CloseReason { code: CloseCode::Normal, description: Some(reason) }));\n// after\nlet description = if reason.len() > 123 { &reason[..123] } else { &reason[..] };\nws.close(Some(CloseReason { code: CloseCode::Normal, description: Some(description.to_string()) }));","handlingStrategy":"validation","validationCode":"fn control_frame_payload_ok(opcode: u8, len: usize) -> bool {\n    !matches!(opcode, 0x8 | 0x9 | 0xA) || len <= 125\n}","typeGuard":"fn is_control_frame(opcode: u8) -> bool {\n    matches!(opcode, 0x8 | 0x9 | 0xA)\n}","tryCatchPattern":"match result {\n    Err(ProtocolError::InvalidLength(n)) => {\n        log::warn!(\"control frame payload of {n} bytes exceeds 125; closing\");\n        close_with(CloseCode::Protocol);\n    }\n    other => handle(other),\n}","preventionTips":["Truncate close-reason text to <=123 bytes and ping payloads to <=125 bytes before sending","Never fragment control frames; send them unfragmented with FIN=1","Add unit tests that assert control-frame size limits in your ws client code","Reject oversized payloads at the application boundary before wrapping them in control frames"],"tags":["websocket","protocol","rfc6455","frame-length"],"backgroundTag":"value-out-of-range","analyzedSha":"c215607f4b6e9ba9accff4a949a33c98f218db20","analyzedAt":"2026-09-09T15:57:34.010Z","contentChangedAt":"2026-09-09T15:57:34.010Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}