siyuan-note/siyuan · error

undeclared raw WebSocket frame

Error message

undeclared raw WebSocket frame: %d

What it means

ValidateRawWebSocketFrame checks that an incoming/outgoing WebSocket frame type is declared in the endpoint's raw WebSocket contract (RawWebSocketDefinition.Frames, defaulting to [1,2,8,9,10]). This error means the frame opcode used is not among the opcodes the endpoint declared, so the kernel rejects the frame as protocol-incompatible with its registered contract.

Solutions

1. Check the frame's WebSocket opcode and use only declared ones: text (1), binary (2), close (8), ping (9), pong (10)
2. If a new opcode is genuinely needed, update the endpoint's RawWebSocketDefinition.Frames to declare it and keep the contract schema in sync
3. Log frameType at the call site to confirm which opcode is actually being sent before changing code

Example fix

// before
conn.WriteMessage(0, payload) // continuation opcode not declared
// after
conn.WriteMessage(1, payload) // declared text frame

const allowedFrames = [1, 2, 8, 9, 10];
if (!allowedFrames.includes(frameType)) throw new Error(`frame type ${frameType} not declared`);

const isDeclaredFrame = (t) => [1, 2, 8, 9, 10].includes(t);

When it happens

Trigger: Calling Bundle.ValidateRawWebSocketFrame with a frameType (WebSocket opcode) that is not listed in the endpoint's Raw.Frames slice — e.g. opcode 0 (continuation), 3-7 (reserved data frames), or 11-15 (reserved control frames) against an endpoint declared via RawWebSocketOptions().

Common situations: Client code sends a continuation frame (opcode 0) as a standalone frame; a proxy or library re-frames messages with an opcode outside 1/2/8/9/10; a new opcode is used after the contract's Frames list was authored; pinging with a nonstandard frame type.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• endpoint does not declare raw WebSocket frames
• invalid plugin WebSocket status
• invalid raw WebSocket declaration
• createEmptyParagraph must be a boolean
• empty plugin response contains a body

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/a6792527d53d4dc4. Report an issue: GitHub.

Appendix: source

Thrown at kernel/apicontract/broadcast_protocol.go:93

	}
	return fmt.Errorf("unregistered API contract: %s %s", method, path)
}

func (b *Bundle) ValidateRawWebSocketFrame(method, path string, incoming bool, frameType int, payload []byte) error {
	for _, endpoint := range b.Endpoints {
		if endpoint.Method == method && endpoint.Path == path {
			if endpoint.WebSocket == nil || endpoint.WebSocket.Raw == nil {
				return fmt.Errorf("endpoint does not declare raw WebSocket frames")
			}
			for _, allowed := range endpoint.WebSocket.Raw.Frames {
				if frameType == allowed {
					if frameType >= 8 && len(payload) > 125 {
						return fmt.Errorf("WebSocket control frame exceeds 125 bytes")
					}
					return nil
				}
			}
			return fmt.Errorf("undeclared raw WebSocket frame: %d", frameType)
		}
	}
	return fmt.Errorf("unregistered API contract: %s %s", method, path)
}

View on GitHub (pinned to 9f775e8a12)