github/copilot-sdk · warning

failed to deserialize session.canvas.opened payload

Error message

failed to deserialize session.canvas.opened payload

What it means

When a session.canvas.opened event arrives, CopilotSession validates the payload with isOpenCanvasInstance before updating its internal open-canvas state. If the payload does not match the expected canvas instance shape, the session logs this warning and skips the upsert, so the canvas will not appear in tracked open canvases.

Solutions

  1. Upgrade the SDK and server to matching versions so the canvas payload schema aligns.
  2. Log the raw event data (patch or wrap the event handler) to see which field failed the isOpenCanvasInstance check.
  3. If events come from a custom transport, verify JSON serialization is not dropping or altering fields.
  4. If you control the payload producer, validate it against the expected canvas instance shape before emitting.
Defensive patterns

Strategy: type-guard

Validate before calling

function isValidCanvasPayload(d: unknown): boolean {
  return typeof d === 'object' && d !== null && typeof (d as any).instanceId === 'string';
}

Type guard

function isOpenCanvasInstance(v: unknown): v is CanvasInstance {
  return (
    typeof v === 'object' &&
    v !== null &&
    typeof (v as { instanceId?: unknown }).instanceId === 'string' &&
    (v as { instanceId: string }).instanceId.length > 0
  );
}

Try / catch

// event-based; guard before use
if (isOpenCanvasInstance(event.data)) {
  trackCanvas(event.data);
} else {
  console.warn('skipping malformed canvas.opened payload', event.data);
}

Prevention

When it happens

Trigger: Server sends a session.canvas.opened event whose data is missing required fields or has wrong types (e.g. not a valid canvas instance object), typically due to a server/client version mismatch or corrupted event payload.

Common situations: Running an older client against a newer server that changed the canvas payload schema; a proxy or custom transport mangling JSON; third-party event replay with partial payloads.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/65e907ce01d26fac. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/src/session.ts:1075

                        mode,
                        elicitationSource,
                        url,
                    },
                    requestId
                );
            }
        } else if (event.type === "capabilities.changed") {
            this._capabilities = { ...this._capabilities, ...event.data };
        } else if (event.type === "session.canvas.opened") {
            this.upsertOpenCanvasFromEvent(event.data);
        } else if (event.type === "session.canvas.closed") {
            this.removeOpenCanvasFromEvent(event.data);
        }
    }

    private upsertOpenCanvasFromEvent(data: unknown): void {
        if (!isOpenCanvasInstance(data)) {
            console.warn("failed to deserialize session.canvas.opened payload");
            return;
        }
        this.upsertOpenCanvas(data);
    }

    private removeOpenCanvasFromEvent(data: unknown): void {
        if (
            !data ||
            typeof data !== "object" ||
            typeof (data as { instanceId?: unknown }).instanceId !== "string" ||
            (data as { instanceId: string }).instanceId.length === 0
        ) {
            console.warn("failed to deserialize session.canvas.closed payload");
            return;
        }
        this.removeOpenCanvas((data as { instanceId: string }).instanceId);
    }

View on GitHub (pinned to cd8cf15dc3)