Debugging Copilot SDK

Enable debug logging and resolve common connection, authentication, and tool execution issues in 코필로트 SDK.

누가 이 기능을 사용할 수 있나요?

GitHub Copilot SDK 는 모든 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.