github/copilot-sdk · error · JsonRpcError

-32603

-32603

Error message

err.message (dynamic CanvasError message)

What it means

CanvasProvider.open() delegates to the user-supplied handler's on_open() and translates a CanvasError into a JSON-RPC error with code -32603 (internal error), carrying the error's message and its to_envelope() data. The displayed message is dynamic: whatever message the CanvasError subclass was raised with. Other exceptions are wrapped via _canvas_handler_error.

Solutions

1. Read the JsonRpcError message/data envelope to see the underlying CanvasError and fix the provider or request accordingly.
2. In your handler's on_open, raise CanvasError subclasses with descriptive messages and structured envelope data.
3. Validate open params (canvas id, view state) before calling open() to avoid provider-side errors.

Example fix

// before
raise CanvasError("something went wrong")

// after
raise CanvasError(
    f"canvas {params.canvas_id!r} not found",
)  # message surfaces verbatim as the JSON-RPC -32603 message

if not canvas_exists(params.canvas_id):
    raise ValueError("canvas does not exist; refusing to open")

def is_canvas_error(err: BaseException) -> TypeGuard[CanvasError]:
    return isinstance(err, CanvasError)

try:
    result = await provider.open(params)
except JsonRpcError as e:
    if e.code == -32603:
        handle_canvas_error(e.message, e.data)  # envelope from CanvasError.to_envelope()
    else:
        raise

When it happens

Trigger: The registered canvas handler's on_open() raises CanvasError (or a subclass) — e.g. the provider rejects the open request because the resource is unavailable, invalid params, or provider-specific failure conditions.

Common situations: Custom Canvas providers raising CanvasError('canvas not found') or similar when the client opens a non-existent canvas; provider-side validation failures surfaced over the session's JSON-RPC bridge.

Related errors

• Request handler must return a JSON-serializable value, got
• canvas_action_no_handler
• -32603
• Copilot request response start() called twice.
• Copilot request response already finished.

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

Appendix: source

Thrown at python/copilot/session.py:1509

    max_prompt_tokens: int
    max_context_window_tokens: int
    max_output_tokens: int
    # Optional capability overrides for the synthesized model.
    capabilities: ModelCapabilitiesOverride


SessionEventHandler = Callable[[SessionEvent], None]


class _CanvasHandlerAdapter:
    def __init__(self, handler: CanvasHandler) -> None:
        self._handler = handler

    async def open(self, params: CanvasProviderOpenRequest) -> CanvasProviderOpenResult:
        try:
            return await self._handler.on_open(params)
        except CanvasError as err:
            raise JsonRpcError(-32603, err.message, data=err.to_envelope()) from err
        except Exception as err:
            raise _canvas_handler_error(err) from err

    async def close(self, params: CanvasProviderCloseRequest) -> None:
        try:
            await self._handler.on_close(params)
        except CanvasError as err:
            raise JsonRpcError(-32603, err.message, data=err.to_envelope()) from err
        except Exception as err:
            raise _canvas_handler_error(err) from err

    async def invoke(self, params: CanvasProviderInvokeActionRequest) -> Any:
        try:
            return await self._handler.on_action(params)
        except CanvasError as err:
            raise JsonRpcError(-32603, err.message, data=err.to_envelope()) from err
        except Exception as err:
            raise _canvas_handler_error(err) from err

View on GitHub (pinned to cd8cf15dc3)