Debugging Copilot SDK

Enable debug logging

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

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

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

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:

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

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 Installing 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:

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

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:

Stdio mode (default):

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

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

TCP mode:

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

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

Connect to existing server:

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

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:

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

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

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.