{"meta":{"title":"Debughandbuch","intro":"In diesem Handbuch werden allgemeine Probleme und Debuggingtechniken für das Copilot SDK in allen unterstützten Sprachen behandelt.","product":"GitHub Copilot","breadcrumbs":[{"href":"/de/copilot","title":"GitHub Copilot"},{"href":"/de/copilot/how-tos","title":"Vorgehensweisen"},{"href":"/de/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/de/copilot/how-tos/copilot-sdk/troubleshooting","title":"Problembehandlung"},{"href":"/de/copilot/how-tos/copilot-sdk/troubleshooting/debugging","title":"Debugging"}],"documentType":"article"},"body":"# Debughandbuch\n\nIn diesem Handbuch werden allgemeine Probleme und Debuggingtechniken für das Copilot SDK in allen unterstützten Sprachen behandelt.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Inhaltsverzeichnis\n\n* [Debugprotokollierung aktivieren](#enable-debug-logging)\n* [Häufige Probleme](#common-issues)\n* [Debuggen von MCP-Servern](#mcp-server-debugging)\n* [Verbindungsprobleme](#connection-issues)\n* [Probleme bei der Toolausführung](#tool-execution-issues)\n* [Plattformspezifische Probleme](#platform-specific-issues)\n\n## Debugprotokollierung aktivieren\n\nDer erste Schritt beim Debuggen ermöglicht ausführliche Protokollierung, um zu sehen, was unter der Haube passiert.\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\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</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient\n\nclient = CopilotClient(log_level=\"debug\")\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nimport copilot \"github.com/github/copilot-sdk/go\"\n\nclient := copilot.NewClient(&copilot.ClientOptions{\n    LogLevel: \"debug\",\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n<!-- docs-validate: skip -->\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<CopilotClient>()\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\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</div>\n\n</div>\n\n### Protokollverzeichnis\n\nDie CLI schreibt Protokolle in ein Verzeichnis. Sie können einen benutzerdefinierten Speicherort angeben:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  cliArgs: [\"--log-dir\", \"/path/to/logs\"],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\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-Protokollierungskonfiguration ist eingeschränkt. Führen Sie zur erweiterten Protokollierung die CLI manuell mit `--log-dir` aus und stellen Sie die Verbindung über `RuntimeConnection.for_uri(...)` her.\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\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</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\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</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n<!-- docs-validate: skip -->\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</div>\n\n</div>\n\n## Häufig auftretende Probleme\n\n### \"CLI nicht gefunden\" / \"Copilot: Befehl nicht gefunden\"\n\n**Ursache:** Die Copilot CLI ist nicht installiert oder nicht im PATH.\n\n**Solution:**\n\n1. Installieren der CLI: [Installationshandbuch](/de/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)\n\n2. Installation überprüfen:\n\n   ```bash\n   copilot --version\n   ```\n\n3. Oder geben Sie den vollständigen Pfad an:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  cliPath: \"/usr/local/bin/copilot\",\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nclient = CopilotClient({\"cli_path\": \"/usr/local/bin/copilot\"})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{Path: \"/usr/local/bin/copilot\"},\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    CliPath = \"/usr/local/bin/copilot\"\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setCliPath(\"/usr/local/bin/copilot\")\n);\n```\n\n</div>\n\n</div>\n\n### \"Nicht authentifiziert\"\n\n**Cause:** Die CLI ist nicht mit GitHub authentifiziert.\n\n**Solution:**\n\n1. Authentifizieren der CLI:\n\n   ```bash\n   copilot auth login\n   ```\n\n2. Oder stellen Sie programmgesteuert ein Token bereit:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  gitHubToken: process.env.GITHUB_TOKEN,\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nimport os\nclient = CopilotClient({\"github_token\": os.environ.get(\"GITHUB_TOKEN\")})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    GitHubToken: os.Getenv(\"GITHUB_TOKEN\"),\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    GitHubToken = Environment.GetEnvironmentVariable(\"GITHUB_TOKEN\")\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setGitHubToken(System.getenv(\"GITHUB_TOKEN\"))\n);\n```\n\n</div>\n\n</div>\n\n### \"Sitzung nicht gefunden\"\n\n**Ursache:** Es wird versucht, eine Sitzung zu verwenden, die zerstört wurde oder nicht vorhanden ist.\n\n**Solution:**\n\n1. Stellen Sie sicher, dass Sie keine Methoden nach diesem `disconnect()`-Aufruf aufrufen:\n\n   ```typescript\n   await session.disconnect();\n   // Don't use session after this!\n   ```\n\n2. Überprüfen Sie bei der Fortsetzung von Sitzungen, ob die Sitzungs-ID vorhanden ist:\n\n   ```typescript\n   const sessions = await client.listSessions();\n   console.log(\"Available sessions:\", sessions);\n   ```\n\n### „Verbindung abgelehnt“ / „ECONNREFUSED“\n\n**Ursache:** Der CLI-Serverprozess ist abgestürzt oder konnte nicht gestartet werden.\n\n**Solution:**\n\n1. Überprüfen Sie, ob die CLI ordnungsgemäß eigenständig ausgeführt wird:\n\n   ```bash\n   copilot --server --stdio\n   ```\n\n2. Überprüfen Sie bei Verwendung des TCP-Modus nach Portkonflikten:\n\n   ```typescript\n   const client = new CopilotClient({\n     useStdio: false,\n     port: 0,  // Use random available port\n   });\n   ```\n\n## Debugging auf dem MCP-Server\n\nMCP-Server (Model Context Protocol) können schwierig zu debuggen sein. Umfassende MCP-Debugginganleitungen finden Sie in der dedizierten **[MCP-Serverdebugginghandbuch](/de/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)**.\n\n### Kurze MCP-Checkliste\n\n* [ ] Die ausführbare Datei des MCP-Servers ist vorhanden und läuft unabhängig.\n* [ ] Befehlspfad ist richtig (absolute Pfade verwenden)\n* [ ] Tools sind aktiviert: `tools: [\"*\"]`\n* [ ] Server antwortet ordnungsgemäß auf `initialize` Anforderung\n* [ ] Das Arbeitsverzeichnis (`cwd`) wird bei Bedarf automatisch festgelegt.\n\n### Testen des MCP-Servers\n\nÜberprüfen Sie vor der Integration mit dem SDK, ob Ihr MCP-Server funktioniert:\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\nEine detaillierte Fehlerbehebung finden Sie unter [MCP-Serverdebugginghandbuch](/de/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging).\n\n## Verbindungsprobleme\n\n### Stdio vs TCP-Modus\n\nDas SDK unterstützt zwei Transportmodi:\n\n| Modus                | Description                                               | Anwendungsfall                        |\n| -------------------- | --------------------------------------------------------- | ------------------------------------- |\n| **Stdio** (Standard) | CLI läuft als Unterprozess, kommuniziert über Rohre       | Lokale Entwicklung, einzelner Prozess |\n| **TCP**              | CLI wird separat ausgeführt, kommuniziert über TCP-Socket | Mehrere Clients, Remote CLI           |\n\n**Stdiomodus (Standard):**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: true,  // This is the default\n});\n```\n\n**TCP-Modus:**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: false,\n  port: 8080,  // Or 0 for random port\n});\n```\n\n**Herstellen einer Verbindung mit vorhandenem Server:**\n\n```typescript\nconst client = new CopilotClient({\n  cliUrl: \"localhost:8080\",  // Connect to running server\n});\n```\n\n### Diagnose von Verbindungsfehlern\n\n1. **Clientstatus überprüfen:**\n\n   ```typescript\n   console.log(\"Connection state:\", client.getState());\n   // Should be \"connected\" after start()\n   ```\n\n2. **Auf Zustandsänderungen warten:**\n\n   ```typescript\n   client.on(\"stateChange\", (state) => {\n     console.log(\"State changed to:\", state);\n   });\n   ```\n\n3. **Überprüfen Sie, ob der CLI-Prozess ausgeführt wird:**\n\n   ```bash\n   # Check for copilot processes\n   ps aux | grep copilot\n   ```\n\n## Probleme bei der Toolausführung\n\n### Benutzerdefiniertes Tool wird nicht aufgerufen\n\n1. **Überprüfen sie die Toolregistrierung:**\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. **Das Überprüfungstoolschema ist ein gültiges 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. **Stellen Sie sicher, dass der Handler gültiges Ergebnis zurückgibt:**\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### Nicht sichtbare Toolfehler\n\nFehlerereignisse abonnieren:\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## Plattformspezifische Probleme\n\n### Windows\n\n1. **Pfadtrennzeichen:** Verwenden Sie unformatierte Zeichenfolgen oder Schrägstriche:\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-Auflösung:** Das SDK behandelt dies automatisch, aber wenn Probleme weiterhin bestehen:\n\n   ```csharp\n   // Explicitly specify .exe\n   Command = \"myserver.exe\"  // Not just \"myserver\"\n   ```\n\n3. **Konsolencodierung:** Stellen Sie UTF-8 für die ordnungsgemäße JSON-Behandlung sicher:\n\n   ```csharp\n   Console.OutputEncoding = System.Text.Encoding.UTF8;\n   ```\n\n### macOS\n\n1. **Gatekeeper-Probleme:** Wenn CLI blockiert ist:\n\n   ```bash\n   xattr -d com.apple.quarantine /path/to/copilot\n   ```\n\n2. **PATH-Probleme in GUI-Apps:** GUI-Anwendungen erben vielleicht nicht den 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. **Berechtigungsprobleme:**\n\n   ```bash\n   chmod +x /path/to/copilot\n   ```\n\n2. **Fehlende Bibliotheken:** Prüfen Sie auf erforderliche geteilte Bibliotheken:\n\n   ```bash\n   ldd /path/to/copilot\n   ```\n\n## Hilfe erhalten\n\nWenn Sie noch hängen bleiben:\n\n1. **Sammeln von Debuginformationen:**\n   * SDK-Version\n   * CLI-Version (`copilot --version`)\n   * Betriebssystem\n   * Debugprotokolle\n   * Minimaler Reproduktionscode\n\n2. **Vorhandene Probleme durchsuchen:**[GitHub Probleme](https://github.com/github/copilot-sdk/issues)\n\n3. **Öffnen Sie ein neues Issue** mit den erfassten Informationen\n\n## Siehe auch\n\n* [Erstellen Sie Ihre erste Copilot-gestützte App](/de/copilot/how-tos/copilot-sdk/getting-started)\n* [AUTOTITLE –](/de/copilot/how-tos/copilot-sdk/features/mcp) MCP-Konfiguration und -Einrichtung\n* [MCP-Serverdebugginghandbuch](/de/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) – Detaillierte MCP-Problembehandlung\n* [API-Referenz](https://github.com/github/copilot-sdk)"}