Debugging Copilot SDK

Enable debug logging and resolve common connection, authentication, and tool execution issues in Copilot SDK.

この機能を使用できるユーザーについて

GitHub Copilot SDK は、すべての Copilot プランで使用できます。

この記事で

メモ

Copilot SDK は現在 テクニカル プレビューです。 機能と可用性は変更される場合があります。

Enable debug logging

To begin troubleshooting, enable verbose logging to gain visibility into the underlying processes.

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  logLevel: "debug",  // Options: "none", "error", "warning", "info", "debug", "all"
});

For examples in Python, Go, and .NET, see Debugging Guide in the github/copilot-sdk repository.

Log directory

The CLI writes logs to the ABC directory by default. You can specify a different location using the --log-dir argument:

TypeScript
const client = new CopilotClient({
  cliArgs: ["--log-dir", "/path/to/logs"],
});

For Python and Go, which do not currently support passing extra CLI arguments, run the CLI manually with --log-dir and connect via the cliUrl option. For more information, see Debugging Guide in the github/copilot-sdk repository.

Common issues

"CLI not found" or "copilot: command not found"

Cause: GitHub Copilot CLI（コマンドラインインターフェース） is not installed or not in PATH.

Solution:

  1. Install the CLI. For more information, see GitHub Copilot CLIをインストールする.

  2. Verify installation:

    Bash
    copilot --version

  3. Or specify the full path:

    TypeScript
    const client = new CopilotClient({
  cliPath: "/usr/local/bin/copilot",
});

    For examples in Python, Go, and .NET, see Debugging Guide in the github/copilot-sdk repository.

"Not authenticated"

Cause: The CLI is not authenticated with GitHub.

Solution:

  1. Authenticate the CLI:

    Bash
    copilot auth login

  2. Or provide a token programmatically:

    TypeScript
    const client = new CopilotClient({
  githubToken: process.env.GITHUB_TOKEN,
});

    For examples in Python, Go, and .NET, see Debugging Guide in the github/copilot-sdk repository.

"Session not found"

Cause: Attempting to use a session that was destroyed or doesn't exist.

Solution:

  1. Ensure you're not calling methods after disconnect():

    TypeScript
    await session.disconnect();
// Don't use session after this!

  2. For resuming sessions, verify the session ID exists:

    TypeScript
    const sessions = await client.listSessions();
console.log("Available sessions:", sessions);

"Connection refused" or "ECONNREFUSED"

Cause: The CLI server process crashed or failed to start.

Solution:

  1. Check if the CLI runs correctly standalone:

    Bash
    copilot --server --stdio

  2. Check for port conflicts if using TCP mode:

    TypeScript
    const client = new CopilotClient({
  useStdio: false,
  port: 0,  // Use random available port
});

MCP server debugging

MCP (Model Context Protocol) servers can be tricky to debug. For comprehensive MCP debugging guidance, see Debugging MCP servers in Copilot SDK.

Quick MCP checklist

  • MCP server executable exists and runs independently
  • Command path is correct (use absolute paths)
  • Tools are enabled: tools: ["*"]
  • Server responds to initialize request correctly
  • Working directory (cwd) is set if needed

Test your MCP server

Before integrating with the SDK, verify your MCP server works:

Bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

For detailed troubleshooting, see Debugging MCP servers in Copilot SDK.

Connection issues

Stdio vs TCP mode

The SDK supports two transport modes:

ModeDescriptionUse case
Stdio (default)CLI runs as subprocess, communicates via pipesLocal development, single process
TCPCLI runs separately, communicates via TCP socketMultiple clients, remote CLI

Stdio mode (default):

TypeScript
const client = new CopilotClient({
  useStdio: true,  // This is the default
});

TCP mode:

TypeScript
const client = new CopilotClient({
  useStdio: false,
  port: 8080,  // Or 0 for random port
});

Connect to existing server:

TypeScript
const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

Diagnosing connection failures

  1. Check client state:

    TypeScript
    console.log("Connection state:", client.getState());
// Should be "connected" after start()

  2. Listen for state changes:

    TypeScript
    client.on("stateChange", (state) => {
  console.log("State changed to:", state);
});

  3. Verify the CLI process is running:

    Bash
    # Check for copilot processes
ps aux | grep copilot

Tool execution issues

Custom tool not being called

  1. Verify tool registration:

    TypeScript
    const session = await client.createSession({
  tools: [myTool],
});

// Check registered tools
console.log("Registered tools:", session.getTools?.());

  2. Check the tool schema is valid JSON Schema:

    TypeScript
    const myTool = {
  name: "get_weather",
  description: "Get weather for a location",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string", description: "City name" },
    },
    required: ["location"],
  },
  handler: async (args) => {
    return { temperature: 72 };
  },
};

  3. Ensure the handler returns a valid result:

    TypeScript
    handler: async (args) => {
  // Must return something JSON-serializable
  return { success: true, data: "result" };

  // Don't return undefined or non-serializable objects
}

Tool errors not surfacing

Subscribe to error events:

TypeScript
session.on("tool.execution_error", (event) => {
  console.error("Tool error:", event.data);
});

session.on("error", (event) => {
  console.error("Session error:", event.data);
});

Platform-specific issues

Windows

  1. Path separators: Use raw strings or forward slashes. For .NET-specific examples, see Debugging Guide in the github/copilot-sdk repository.

  2. Console encoding: Ensure UTF-8 for proper JSON handling. For .NET-specific examples, see Debugging Guide in the github/copilot-sdk repository.

macOS

  1. Gatekeeper issues: If CLI is blocked:

    Bash
    xattr -d com.apple.quarantine /path/to/copilot

  2. PATH issues in GUI apps: GUI applications may not inherit shell PATH:

    TypeScript
    const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});

Linux

  1. Permission issues:

    Bash
    chmod +x /path/to/copilot

  2. Missing libraries: Check for required shared libraries:

    Bash
    ldd /path/to/copilot

Getting help

If you're still stuck, collect the following debug information before opening an issue:

  • SDK version
  • CLI version (copilot --version)
  • Operating system
  • Debug logs
  • Minimal reproduction code

Search for existing issues or open a new issue in the github/copilot-sdk repository.