# Fehlerbehebung — Unreal Engine · AI Game Developer Wiki Behebe häufige Unreal-MCP-Probleme – Plugin lädt nicht, Bridge fehlt, Verbindung hängt, Agent ohne Unreal-Tools, veraltete Builds und Tool-Fehler. Diese Seite wurde maschinell aus dem Englischen übersetzt. [Englisches Original lesen](https://ai-game.dev/docs/wiki/unreal/troubleshooting). Diese Seite listet die Probleme auf, die bei Unreal MCP am häufigsten auftreten, und wie du sie behebst. Beginne mit den Schnellchecks und springe dann zum passenden Abschnitt. ## Schnellchecks 1. **Ist das Plugin geladen?** Im Output Log sollte nach dem Start des Editors `[Unreal-MCP] plugin loaded` stehen. 2. **Was zeigt das Fenster an?** Öffne **Tools**, **AI Game Developer** und lies die Statuszeile (Connected, Connecting, Reconnecting, Disconnected oder No MCP bridge). 3. **Was sieht die CLI?** Führe `unreal-mcp-cli status --path ./YourProject` aus. 4. **Lies das Log.** Nutze **Open log file** im Fenster, filtere das Output Log nach der Kategorie `LogUnrealMcp` oder frage den Agenten nach `console | where Verbosity == "Error"`. ## Das Plugin lädt nicht Wenn keine Zeile `[Unreal-MCP] plugin loaded` erscheint, konnte das Editor-Modul nicht starten. - Suche im Output Log nach einem Startfehler des Plugins oder nach einer beschädigten `.uplugin`. - Stelle sicher, dass das Projekt ein **C++-Projekt** mit funktionierender Compiler-Toolchain ist. Siehe [Installation](https://ai-game.dev/de/docs/wiki/unreal/installation#requirements). - Wenn Unreal meldet, dass Module fehlen oder das Plugin inkompatibel ist, lasse es neu bauen, oder öffne das Projekt mit `unreal-mcp-cli open ./YourProject`, das zuerst die nativen Module baut und diese Hinweise wegklickt. ## Ein Update zeigt keine Wirkung Der inkrementelle Build von Unreal kann alten Plugin-Code behalten, wenn sich der Quellcode des Plugins ändert, aber sein alter Ordner `Intermediate/` erhalten bleibt. - Aktualisiere mit `unreal-mcp-cli update ./YourProject`, das den Build-Cache standardmäßig bereinigt. - Nach einem manuellen Kopieren: Schließe den Editor, lösche `Plugins/UnrealMCP/Intermediate/` und die C++-Dateien in `Plugins/UnrealMCP/Binaries/` (behalte `Binaries/ThirdParty/`) und öffne ihn dann erneut. ## "No MCP bridge" oder die Bridge startet immer wieder neu Das Plugin benötigt seinen Bridge-Prozess `unreal-mcp-bridge`. Das Fenster zeigt den Bridge-Status und einen Neustart-Zähler. - Wenn im Log `no sidecar binary resolved for rid ` steht, wurde keine Bridge gefunden. - **App- oder CLI-Installation:** Die Bridge ist mitgeliefert. Installiere sie mit `unreal-mcp-cli install-plugin ./YourProject` neu (oder über die App); möglicherweise fehlt in dem Paket deine Plattform. - **Source-Checkout:** Baue eine mit `unreal-mcp-cli bootstrap-local ./YourProject` oder setze `UNREAL_MCP_BRIDGE_PATH`. - Klicke in der Fußzeile des Fensters auf **Restart bridge**, nachdem du die Ursache behoben hast. ## Hängt bei "Connecting" oder "Reconnecting" - **Cloud-Modus:** Prüfe, ob du angemeldet bist. Wenn das Fenster "Sign in required" anzeigt, ist deine gespeicherte Anmeldung abgelaufen; klicke auf **Authorize** und bestätige den neuen Code. - Prüfe, ob die Maschine ai-game.dev erreichen kann (Proxy- oder Firewall-Regeln). - **Custom-Modus:** Stelle sicher, dass der lokale Server läuft (**Start** in der MCP-Server-Karte oder `--start-server`) und dass die **Server URL** darauf verweist. - Nutze **Disconnect** und dann **Connect** oder **Restart bridge**. ## Lokaler Server meldet "No connected clients" Wenn ein lokaler `gamedev-mcp-server` `No connected clients. Retrying` loggt und dann mit HTTP 500 antwortet, ist der Editor noch im Modus **Cloud** und mit ai-game.dev statt mit deinem lokalen Server verbunden. Wechsle im Fenster auf **Custom**, setze `UNREAL_MCP_CONNECTION_MODE=Custom` oder übergib `--connection-mode Custom` (oder `--host`) an `unreal-mcp-cli open`. ## Der AI-Agent hat keine Unreal-Tools - Prüfe die Konfiguration des Agenten: Führe `unreal-mcp-cli setup-mcp --path ./YourProject --dry-run` aus und vergleiche, oder klicke im Bereich für den AI-Agenten auf **Configure** (oder **Reconfigure**). - Starte oder lade den Agenten nach den Konfigurationsänderungen neu. Viele Clients lesen MCP-Konfigurationen nur beim Start. - Claude Code liest `.mcp.json` aus dem Ordner, in dem du es startest; starte es daher im Projektordner. - Wenn du mit `setup-mcp` konfiguriert hast, bevor du den Editor jemals geöffnet hast, verweist die Konfiguration möglicherweise auf `localhost` statt auf die Cloud. Öffne das Projekt einmal und führe dann `setup-mcp` erneut aus, oder übergib `--url`. - Prüfe die Zeile **AI agents** im Bereich Connection. Wenn dein Agent dort nicht aufgeführt ist, ist er nicht mit demselben Server wie der Editor verbunden. - Wenn du Tools im Fenster **MCP Tools** ausgeblendet oder `UNREAL_MCP_TOOLS` gesetzt hast, sieht der Agent weniger Tools. ## Der Agent erreicht den falschen Editor Wenn mehrere Editoren unter einem Konto laufen, nutze die projektgebundene URL (`/mcp/p/`), die `setup-mcp` standardmäßig schreibt. Führe `setup-mcp` erneut ohne `--no-pin` aus. Siehe [Connecting AI clients](https://ai-game.dev/de/docs/wiki/unreal/connecting-ai-clients#pinned-url). ## 401-Fehler im Agenten - Im Cloud-Modus muss sich der Agent bei einer reinen URL-Konfiguration selbst anmelden. Lass ihn entweder seinen OAuth-Sign-in ausführen oder melde die Maschine an (`unreal-mcp-cli login`) und führe `setup-mcp` erneut aus, damit die Konfiguration einen Projektschlüssel enthält. - Wenn der Projektschlüssel widerrufen wurde, verwende **Regenerate key** im Editor oder `setup-mcp --regenerate-key`. - Im Custom-Modus mit **token**-Authentifizierung muss die Konfiguration dasselbe Token enthalten wie der Editor. Verwende **Reconfigure**, nachdem du ein neues Token erzeugt hast. ## Tool-Aufrufe laufen in ein Timeout Ein Tool-Aufruf darf standardmäßig 5 Minuten laufen. Erhöhe `UNREAL_MCP_TOOL_TIMEOUT` (Millisekunden) für lange Python-Skripte oder große Importe. `python-execute` hat außerdem ein eigenes `timeout` (Standard 30 Sekunden), das der Agent pro Aufruf setzen kann. ## Screenshot-Tools geben einen Fehler zurück Pixel-Capture benötigt einen Editor mit GPU-Unterstützung. Unter `-nullrhi` geben die Screenshot-Tools einen strukturierten Fehler zurück. `unreal-mcp-cli exec` und `open --headless` starten Editoren, die off-screen rendern, daher funktionieren Aufnahmen dort weiterhin. ## Python-Tools schlagen fehl `python-execute` verwendet Unreals Python Editor Script Plugin, das Unreal MCP aktiviert. Wenn Python nicht verfügbar ist, prüfe, ob das Plugin unter **Edit, Plugins** aktiviert ist. Fehler verweisen auf Zeilen von `snippet.py`, also den Code, den der Agent gesendet hat. ## Erweiterung wird nicht angezeigt - Erweiterungen benötigen Unreal Engine 5.7 oder neuer und Unreal MCP 0.26.0 oder neuer. - Nach der Installation muss die Erweiterung kompiliert werden: Öffne den Editor erneut, verwende `--build` oder **Compile (Live Coding)** im Abschnitt Extensions. - Prüfe, ob die Erweiterung im Abschnitt Extensions aktiviert ist. ## Immer noch nicht weiter? - Siehe die [FAQ](https://ai-game.dev/de/docs/wiki/unreal/faq) und die allgemeine [FAQ](https://ai-game.dev/docs/faq). - Verwende **Help / Talk** im Fenster, um auf Discord zu fragen, oder **Bug Report**, um ein GitHub-Issue zu öffnen. Gib die Unreal-Version, dein Betriebssystem, die Statuszeile des Fensters und die relevanten Logzeilen an (niemals deine Tokens). --- Source (HTML): https://ai-game.dev/de/docs/wiki/unreal/troubleshooting Machine-translated (de) from the English page: https://ai-game.dev/docs/wiki/unreal/troubleshooting