{"meta":{"title":"Debugging guide","intro":"This guide covers common issues and debugging techniques for the Copilot SDK across all supported languages.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos","title":"How-tos"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting","title":"Troubleshooting"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging","title":"Debugging"}],"documentType":"article"},"body":"# Debugging guide\n\nThis guide covers common issues and debugging techniques for the Copilot SDK across all supported languages.\n\n\n\n\n\n## Table of contents\n\n* [Enable Debug Logging](#enable-debug-logging)\n* [Common Issues](#common-issues)\n* [MCP Server Debugging](#mcp-server-debugging)\n* [Connection Issues](#connection-issues)\n* [Tool Execution Issues](#tool-execution-issues)\n* [Platform-Specific Issues](#platform-specific-issues)\n\n## Enable debug logging\n\nThe first step in debugging is enabling verbose logging to see what's happening under the hood.\n\n
\n
TypeScript
\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n logLevel: \"debug\", // Options: \"none\", \"error\", \"warning\", \"info\", \"debug\", \"all\"\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import CopilotClient\n\nclient = CopilotClient(log_level=\"debug\")\n```\n\n
\n\n
Go
\n\n```golang\nimport copilot \"github.com/github/copilot-sdk/go\"\n\nclient := copilot.NewClient(&copilot.ClientOptions{\n LogLevel: \"debug\",\n})\n```\n\n
\n\n
.NET
\n\n\n\n```csharp\nusing GitHub.Copilot;\nusing Microsoft.Extensions.Logging;\n\n// Using ILogger\nvar loggerFactory = LoggerFactory.Create(builder =>\n{\n builder.SetMinimumLevel(LogLevel.Debug);\n builder.AddConsole();\n});\n\nvar client = new CopilotClient(new CopilotClientOptions\n{\n LogLevel = \"debug\",\n Logger = loggerFactory.CreateLogger()\n});\n```\n\n
\n\n
Java
\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\nvar client = new CopilotClient(new CopilotClientOptions()\n .setLogLevel(\"debug\")\n);\n```\n\n
\n\n
\n\n### Log directory\n\nThe CLI writes logs to a directory. You can specify a custom location:\n\n
\n
TypeScript
\n\n```typescript\nconst client = new CopilotClient({\n cliArgs: [\"--log-dir\", \"/path/to/logs\"],\n});\n```\n\n
\n\n
Python
\n\n```python\n# The Python SDK does not currently support passing extra CLI arguments.\n# Logs are written to the default location or can be configured via\n# the CLI when running in server mode.\n```\n\n> \\[!NOTE]\n> Python SDK logging configuration is limited. For advanced logging, run the CLI manually with `--log-dir` and connect via `RuntimeConnection.for_uri(...)`.\n\n
\n\n
Go
\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n Connection: copilot.StdioConnection{\n Args: []string{\"--log-dir\", \"/path/to/logs\"},\n },\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n Connection = RuntimeConnection.ForStdio(args: new[] { \"--log-dir\", \"/path/to/logs\" })\n});\n```\n\n
\n\n
Java
\n\n\n\n```java\n// The Java SDK does not currently support passing extra CLI arguments.\n// For custom log directories, run the CLI manually with --log-dir\n// and connect via cliUrl.\n```\n\n
\n\n
\n\n## Common issues\n\n### \"CLI not found\" / \"Copilot: command not found\"\n\n**Cause:** The Copilot CLI is not installed or not in PATH.\n\n**Solution:**\n\n1. Install the CLI: [Installation guide](/en/enterprise-cloud@latest/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)\n\n2. Verify installation:\n\n ```bash\n copilot --version\n ```\n\n3. Or specify the full path:\n\n
\n
JavaScript
\n\n```typescript\nconst client = new CopilotClient({\n cliPath: \"/usr/local/bin/copilot\",\n});\n```\n\n
\n\n
Python
\n\n```python\nclient = CopilotClient({\"cli_path\": \"/usr/local/bin/copilot\"})\n```\n\n
\n\n
Go
\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n Connection: copilot.StdioConnection{Path: \"/usr/local/bin/copilot\"},\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n CliPath = \"/usr/local/bin/copilot\"\n});\n```\n\n
\n\n
Java
\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n .setCliPath(\"/usr/local/bin/copilot\")\n);\n```\n\n
\n\n
\n\n### \"Not authenticated\"\n\n**Cause:** The CLI is not authenticated with GitHub.\n\n**Solution:**\n\n1. Authenticate the CLI:\n\n ```bash\n copilot auth login\n ```\n\n2. Or provide a token programmatically:\n\n
\n
JavaScript
\n\n```typescript\nconst client = new CopilotClient({\n gitHubToken: process.env.GITHUB_TOKEN,\n});\n```\n\n
\n\n
Python
\n\n```python\nimport os\nclient = CopilotClient({\"github_token\": os.environ.get(\"GITHUB_TOKEN\")})\n```\n\n
\n\n
Go
\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n GitHubToken: os.Getenv(\"GITHUB_TOKEN\"),\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n GitHubToken = Environment.GetEnvironmentVariable(\"GITHUB_TOKEN\")\n});\n```\n\n
\n\n
Java
\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n .setGitHubToken(System.getenv(\"GITHUB_TOKEN\"))\n);\n```\n\n
\n\n
\n\n### \"Session not found\"\n\n**Cause:** Attempting to use a session that was destroyed or doesn't exist.\n\n**Solution:**\n\n1. Ensure you're not calling methods after `disconnect()`:\n\n ```typescript\n await session.disconnect();\n // Don't use session after this!\n ```\n\n2. For resuming sessions, verify the session ID exists:\n\n ```typescript\n const sessions = await client.listSessions();\n console.log(\"Available sessions:\", sessions);\n ```\n\n### \"Connection refused\" / \"ECONNREFUSED\"\n\n**Cause:** The CLI server process crashed or failed to start.\n\n**Solution:**\n\n1. Check if the CLI runs correctly standalone:\n\n ```bash\n copilot --server --stdio\n ```\n\n2. Check for port conflicts if using TCP mode:\n\n ```typescript\n const client = new CopilotClient({\n useStdio: false,\n port: 0, // Use random available port\n });\n ```\n\n## MCP server debugging\n\nMCP (Model Context Protocol) servers can be tricky to debug. For comprehensive MCP debugging guidance, see the dedicated **[MCP server debugging guide](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)**.\n\n### Quick MCP checklist\n\n* [ ] MCP server executable exists and runs independently\n* [ ] Command path is correct (use absolute paths)\n* [ ] Tools are enabled: `tools: [\"*\"]`\n* [ ] Server responds to `initialize` request correctly\n* [ ] Working directory (`cwd`) is set if needed\n\n### Test your MCP server\n\nBefore integrating with the SDK, verify your MCP server works:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n```\n\nSee [MCP server debugging guide](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) for detailed troubleshooting.\n\n## Connection issues\n\n### stdio vs TCP mode\n\nThe SDK supports two transport modes:\n\n| Mode | Description | Use Case |\n| ------------------- | ------------------------------------------------ | --------------------------------- |\n| **Stdio** (default) | CLI runs as subprocess, communicates via pipes | Local development, single process |\n| **TCP** | CLI runs separately, communicates via TCP socket | Multiple clients, remote CLI |\n\n**Stdio mode (default):**\n\n```typescript\nconst client = new CopilotClient({\n useStdio: true, // This is the default\n});\n```\n\n**TCP mode:**\n\n```typescript\nconst client = new CopilotClient({\n useStdio: false,\n port: 8080, // Or 0 for random port\n});\n```\n\n**Connect to existing server:**\n\n```typescript\nconst client = new CopilotClient({\n cliUrl: \"localhost:8080\", // Connect to running server\n});\n```\n\n### Diagnosing connection failures\n\n1. **Check client state:**\n\n ```typescript\n console.log(\"Connection state:\", client.getState());\n // Should be \"connected\" after start()\n ```\n\n2. **Listen for state changes:**\n\n ```typescript\n client.on(\"stateChange\", (state) => {\n console.log(\"State changed to:\", state);\n });\n ```\n\n3. **Verify CLI process is running:**\n\n ```bash\n # Check for copilot processes\n ps aux | grep copilot\n ```\n\n## Tool execution issues\n\n### Custom tool not being called\n\n1. **Verify tool registration:**\n\n ```typescript\n const session = await client.createSession({\n tools: [myTool],\n });\n\n // Check registered tools\n console.log(\"Registered tools:\", session.getTools?.());\n ```\n\n2. **Check tool schema is valid JSON Schema:**\n\n ```typescript\n const myTool = {\n name: \"get_weather\",\n description: \"Get weather for a location\",\n parameters: {\n type: \"object\",\n properties: {\n location: { type: \"string\", description: \"City name\" },\n },\n required: [\"location\"],\n },\n handler: async (args) => {\n return { temperature: 72 };\n },\n };\n ```\n\n3. **Ensure handler returns valid result:**\n\n ```typescript\n handler: async (args) => {\n // Must return something JSON-serializable\n return { success: true, data: \"result\" };\n \n // Don't return undefined or non-serializable objects\n }\n ```\n\n### Tool errors not surfacing\n\nSubscribe to error events:\n\n```typescript\nsession.on(\"tool.execution_error\", (event) => {\n console.error(\"Tool error:\", event.data);\n});\n\nsession.on(\"error\", (event) => {\n console.error(\"Session error:\", event.data);\n});\n```\n\n## Platform-specific issues\n\n### Windows\n\n1. **Path separators:** Use raw strings or forward slashes:\n\n ```csharp\n CliPath = @\"C:\\Program Files\\GitHub\\copilot.exe\"\n // or\n CliPath = \"C:/Program Files/GitHub/copilot.exe\"\n ```\n\n2. **PATHEXT resolution:** The SDK handles this automatically, but if issues persist:\n\n ```csharp\n // Explicitly specify .exe\n Command = \"myserver.exe\" // Not just \"myserver\"\n ```\n\n3. **Console encoding:** Ensure UTF-8 for proper JSON handling:\n\n ```csharp\n Console.OutputEncoding = System.Text.Encoding.UTF8;\n ```\n\n### macOS\n\n1. **Gatekeeper issues:** If CLI is blocked:\n\n ```bash\n xattr -d com.apple.quarantine /path/to/copilot\n ```\n\n2. **PATH issues in GUI apps:** GUI applications may not inherit shell PATH:\n\n ```typescript\n const client = new CopilotClient({\n cliPath: \"/opt/homebrew/bin/copilot\", // Full path\n });\n ```\n\n### Linux\n\n1. **Permission issues:**\n\n ```bash\n chmod +x /path/to/copilot\n ```\n\n2. **Missing libraries:** Check for required shared libraries:\n\n ```bash\n ldd /path/to/copilot\n ```\n\n## Getting help\n\nIf you're still stuck:\n\n1. **Collect debug information:**\n * SDK version\n * CLI version (`copilot --version`)\n * Operating system\n * Debug logs\n * Minimal reproduction code\n\n2. **Search existing issues:** [GitHub Issues](https://github.com/github/copilot-sdk/issues)\n\n3. **Open a new issue** with the collected information\n\n## See also\n\n* [Build your first Copilot-powered app](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started)\n* [Using MCP servers with the GitHub Copilot SDK](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/mcp) - MCP configuration and setup\n* [MCP server debugging guide](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) - Detailed MCP troubleshooting\n* [API Reference](https://github.com/github/copilot-sdk)"}