awesome-copilot/cookbook/copilot-sdk/python/error-handling.md

Error Handling Patterns

Handle errors gracefully in your Copilot SDK applications.

Runnable example: recipe/error_handling.py

cd recipe && pip install -r requirements.txt
python error_handling.py

Example scenario

You need to handle various error conditions like connection failures, timeouts, and invalid responses.

Basic try-except

from copilot import CopilotClient

client = CopilotClient()

try:
    client.start()
    session = client.create_session(model="gpt-5")

    response = None
    def handle_message(event):
        nonlocal response
        if event["type"] == "assistant.message":
            response = event["data"]["content"]

    session.on(handle_message)
    session.send(prompt="Hello!")
    session.wait_for_idle()

    if response:
        print(response)

    session.destroy()
except Exception as e:
    print(f"Error: {e}")
finally:
    client.stop()

Handling specific error types

import subprocess

try:
    client.start()
except FileNotFoundError:
    print("Copilot CLI not found. Please install it first.")
except ConnectionError:
    print("Could not connect to Copilot CLI server.")
except Exception as e:
    print(f"Unexpected error: {e}")

Timeout handling

import signal
from contextlib import contextmanager

@contextmanager
def timeout(seconds):
    def timeout_handler(signum, frame):
        raise TimeoutError("Request timed out")

    old_handler = signal.signal(signal.SIGALRM, timeout_handler)
    signal.alarm(seconds)
    try:
        yield
    finally:
        signal.alarm(0)
        signal.signal(signal.SIGALRM, old_handler)

session = client.create_session(model="gpt-5")

try:
    session.send(prompt="Complex question...")

    # Wait with timeout (30 seconds)
    with timeout(30):
        session.wait_for_idle()

    print("Response received")
except TimeoutError:
    print("Request timed out")

Aborting a request

import threading

session = client.create_session(model="gpt-5")

# Start a request
session.send(prompt="Write a very long story...")

# Abort it after some condition
def abort_later():
    import time
    time.sleep(5)
    session.abort()
    print("Request aborted")

threading.Thread(target=abort_later).start()

Graceful shutdown

import signal
import sys

def signal_handler(sig, frame):
    print("\nShutting down...")
    errors = client.stop()
    if errors:
        print(f"Cleanup errors: {errors}")
    sys.exit(0)

signal.signal(signal.SIGINT, signal_handler)

Context manager for automatic cleanup

from copilot import CopilotClient

with CopilotClient() as client:
    client.start()
    session = client.create_session(model="gpt-5")

    # ... do work ...

    # client.stop() is automatically called when exiting context

Best practices

1. Always clean up: Use try-finally or context managers to ensure stop() is called
2. Handle connection errors: The CLI might not be installed or running
3. Set appropriate timeouts: Long-running requests should have timeouts
4. Log errors: Capture error details for debugging