debug-copilot-sdk.md

title	Debugging Copilot SDK
shortTitle	Debug Copilot SDK
intro	Enable debug logging and resolve common connection, authentication, and tool execution issues in {% data variables.copilot.copilot_sdk_short %}.
product	{% data reusables.gated-features.copilot-sdk %}
versions	feature copilot
contentType	how-tos

{% data reusables.copilot.copilot-sdk.technical-preview-note %}

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"
});

For examples in Python, Go, and .NET, see Debugging Guide in the github/copilot-sdk repository. {% data reusables.copilot.copilot-sdk.java-sdk-link %}

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"],
});

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: {% data variables.copilot.copilot_cli %} is not installed or not in PATH.

Solution:

1. Install the CLI. For more information, see AUTOTITLE.

2. Verify installation:

   copilot --version

3. Or specify the full path:

   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. {% data reusables.copilot.copilot-sdk.java-sdk-link %}

"Not authenticated"

Cause: The CLI is not authenticated with {% data variables.product.github %}.

Solution:

1. Authenticate the CLI:

   copilot auth login

2. Or provide a token programmatically:

   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. {% data reusables.copilot.copilot-sdk.java-sdk-link %}

"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():

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

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

   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:

   copilot --server --stdio

2. Check for port conflicts if using TCP mode:

   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 AUTOTITLE.

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

For detailed troubleshooting, see AUTOTITLE.

Connection issues

Stdio vs TCP mode

The SDK supports two transport modes:

Mode	Description	Use case
Stdio (default)	CLI runs as subprocess, communicates via pipes	Local development, single process
TCP	CLI runs separately, communicates via TCP socket	Multiple clients, remote CLI

Stdio mode (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
});

Connect to existing server:

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

Diagnosing connection failures

1. Check client state:

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

2. Listen for state changes:

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

3. Verify the CLI process is running:

   # Check for copilot processes
   ps aux | grep copilot

Tool execution issues

Custom tool not being called

1. Verify tool registration:

   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:

   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:

   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);
});

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:

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

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

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

Linux

1. Permission issues:

   chmod +x /path/to/copilot

2. Missing libraries: Check for required shared libraries:

   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.