Debugging guide

Table of contents

• Enable Debug Logging
• Common Issues
• MCP Server Debugging
• Connection Issues
• Tool Execution Issues
• Platform-Specific Issues

Enable debug logging

The first step in debugging is enabling verbose logging to see what's happening under the hood.

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

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

from copilot import CopilotClient

client = CopilotClient(log_level="debug")

package main

import copilot "github.com/github/copilot-sdk/go"

func main() {
	client := copilot.NewClient(&copilot.ClientOptions{
		LogLevel: "debug",
	})
	_ = client
}

import copilot "github.com/github/copilot-sdk/go"

client := copilot.NewClient(&copilot.ClientOptions{
    LogLevel: "debug",
})

using GitHub.Copilot;
using Microsoft.Extensions.Logging;

// Using ILogger
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.SetMinimumLevel(LogLevel.Debug);
    builder.AddConsole();
});

var client = new CopilotClient(new CopilotClientOptions
{
    LogLevel = "debug",
    Logger = loggerFactory.CreateLogger<CopilotClient>()
});

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

var client = new CopilotClient(new CopilotClientOptions()
    .setLogLevel("debug")
);

Log directory

The CLI writes logs to a directory. You can specify a custom location:

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

# The Python SDK does not currently support passing extra CLI arguments.
# Logs are written to the default location or can be configured via
# the CLI when running in server mode.

package main

import copilot "github.com/github/copilot-sdk/go"

func main() {
	client := copilot.NewClient(&copilot.ClientOptions{
		Connection: copilot.StdioConnection{
			Args: []string{"--log-dir", "/path/to/logs"},
		},
	})
	_ = client
}

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{
        Args: []string{"--log-dir", "/path/to/logs"},
    },
})

var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForStdio(args: new[] { "--log-dir", "/path/to/logs" })
});

// The Java SDK does not currently support passing extra CLI arguments.
// For custom log directories, run the CLI manually with --log-dir
// and connect via cliUrl.

Common issues

"CLI not found" / "Copilot: command not found"

Cause: The Copilot CLI is not installed or not in PATH.

Solution:

1. Install the CLI: Installation guide

2. Verify installation:

   copilot --version
   

3. Or specify the full path:

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

client = CopilotClient({"cli_path": "/usr/local/bin/copilot"})

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{Path: "/usr/local/bin/copilot"},
})

var client = new CopilotClient(new CopilotClientOptions
{
    CliPath = "/usr/local/bin/copilot"
});

var client = new CopilotClient(new CopilotClientOptions()
    .setCliPath("/usr/local/bin/copilot")
);

"Not authenticated"

Cause: The CLI is not authenticated with GitHub.

Solution:

1. Authenticate the CLI:

   copilot auth login
   

2. Or provide a token programmatically:

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

import os
client = CopilotClient({"github_token": os.environ.get("GITHUB_TOKEN")})

client := copilot.NewClient(&copilot.ClientOptions{
    GithubToken: os.Getenv("GITHUB_TOKEN"),
})

var client = new CopilotClient(new CopilotClientOptions
{
    GithubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN")
});

var client = new CopilotClient(new CopilotClientOptions()
    .setGitHubToken(System.getenv("GITHUB_TOKEN"))
);

"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" / "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 the dedicated MCP server debugging guide.

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

See MCP server debugging guide for detailed troubleshooting.

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

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 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 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 handler returns 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:

   CliPath = @"C:\Program Files\GitHub\copilot.exe"
   // or
   CliPath = "C:/Program Files/GitHub/copilot.exe"
   

2. PATHEXT resolution: The SDK handles this automatically, but if issues persist:

   // Explicitly specify .exe
   Command = "myserver.exe"  // Not just "myserver"
   

3. Console encoding: Ensure UTF-8 for proper JSON handling:

   Console.OutputEncoding = System.Text.Encoding.UTF8;
   

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:

1. Collect debug information:

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

2. Search existing issues: GitHub Issues

3. Open a new issue with the collected information

See also

• Build your first Copilot-powered app
• Using MCP servers with the GitHub Copilot SDK - MCP configuration and setup
• MCP server debugging guide - Detailed MCP troubleshooting
• API Reference