siyuan-note/siyuan · error

endpoint does not declare raw SSE events

Error message

endpoint does not declare raw SSE events

What it means

ValidateRawSSEEvent looks up the endpoint by method+path in the bundle and requires it to have both an SSE definition and Raw mode enabled. If the endpoint exists but is not declared as raw SSE (or has no SSE at all), this error is returned. It prevents validating raw byte events against an endpoint whose SSE contract is evented or absent.

Solutions

1. Declare the endpoint with RawSSEOptions() (SSE with Raw set) in the contract
2. Verify the method and path arguments exactly match the registered endpoint
3. Update the caller to use the evented SSE validation path if the endpoint is evented
4. Regenerate/rebuild the bundle so it contains the current endpoint definitions

Example fix

// before
// endpoint declared: SSE: &SSEDefinition{Events: events}  (evented)
bundle.ValidateRawSSEEvent("GET", "/api/raw", name, id, retry, payload)
// after
SSE: RawSSEOptions().SSE
bundle.ValidateRawSSEEvent("GET", "/api/raw", name, id, retry, payload)

const ep = bundle.Endpoints.find(e => e.Method === method && e.Path === path);
if (!ep) throw new Error("unregistered: " + method + " " + path);
if (!ep.SSE?.Raw) throw new Error("endpoint is not raw SSE");

function isRawSSEEndpoint(ep) { return !!ep?.SSE?.Raw; }

try { bundle.ValidateRawSSEEvent(method, path, name, id, retry, payload); } catch (e) { if (String(e).includes("does not declare raw SSE events")) switchToEventedValidation(); else throw e; }

When it happens

Trigger: Calling bundle.ValidateRawSSEEvent(method, path, ...) for an endpoint whose contract declares named SSE events (SSE != nil but Raw == nil) or no SSE definition at all.

Common situations: Client code switched from evented to raw SSE (or vice versa) without updating the contract; calling the raw validator with the wrong method/path so it matches a non-SSE endpoint; contract and server code drifted after a refactor.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• endpoint does not declare raw WebSocket frames
• invalid plugin SSE status
• invalid raw SSE event declaration
• unregistered API contract
• createEmptyParagraph must be a boolean

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

Appendix: source

Thrown at kernel/apicontract/broadcast_protocol.go:71

	}
	if status == 200 && len(payload) == 0 && schema.Raw.EmptyClosedResponse {
		return true, nil
	}
	media, _, _ := mime.ParseMediaType(contentType)
	for _, allowed := range schema.Raw.UpgradeErrorStatuses {
		if status == allowed && media == "text/plain" {
			return true, nil
		}
	}
	return false, nil
}

// ValidateRawSSEEvent 校验事件协议；事件数据是原始字节，不进行 JSON 解码或 Base64 转码。
func (b *Bundle) ValidateRawSSEEvent(method, path, name, id string, retry uint, payload []byte) error {
	for _, endpoint := range b.Endpoints {
		if endpoint.Method == method && endpoint.Path == path {
			if endpoint.SSE == nil || endpoint.SSE.Raw == nil {
				return fmt.Errorf("endpoint does not declare raw SSE events")
			}
			return nil
		}
	}
	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")
					}

View on GitHub (pinned to 9f775e8a12)