Troubleshooting

On This Page

• Connection Issues
• Plugin Loading
• Method Errors
• GraphRAG Issues
• MCP Configuration
• Performance

Connection Issues

WebSocket connection refused

Symptom: Client receives "connection refused" when connecting to ws://localhost:9877.

Cause: The AgentUX plugin is not loaded, the editor is not running, or the WebSocket server failed to bind to port 9877.

Solution:

1. Confirm the Unreal Editor is running and the AgentUX plugin is enabled in Edit > Plugins.
2. Check the Output Log (Window > Output Log) for LogAgentUX messages. A successful startup shows:

   LogAgentUX: WebSocket server listening on port 9877

3. Verify the port is open:

   netstat -an | findstr 9877

4. If no output appears, the plugin did not start. See the Plugin Loading section below.

Port 9877 already in use

Symptom: Output Log shows a bind error, or a second editor instance fails to start the WebSocket server.

Cause: Another process (often a previous editor instance) is already bound to port 9877.

Solution:

1. Find the process holding the port:

   netstat -ano | findstr 9877

2. Identify the PID in the last column and check if it is another editor instance.
3. Close the other editor, or terminate the process if it is stale:

   taskkill /PID <pid> /F

4. Restart the editor. Only one instance of the AgentUX WebSocket server can bind to port 9877 at a time.

Origin header rejected

Symptom: WebSocket connection is immediately closed by the server after the handshake.

Cause: The AgentUX WebSocket server requires an Origin header on all connections for security. Some clients omit it by default.

Solution: Include the Origin header in your connection request. For example, in Python:

import websockets

ws = await websockets.connect(
    "ws://localhost:9877",
    additional_headers={"Origin": "http://localhost"}
)

The MCP bridge handles this automatically. This issue only affects custom scripts or third-party clients.

Connection drops after idle timeout

Symptom: A long-running connection silently disconnects after several minutes of inactivity.

Cause: Network middleware, firewalls, or proxy software may close idle TCP connections.

Solution:

1. Send periodic agentux.ping requests as a keepalive:

   {"jsonrpc": "2.0", "id": 1, "method": "agentux.ping"}

2. If using the MCP bridge, it manages keepalive automatically. Check that no local firewall or antivirus is interfering with localhost connections.

Plugin Loading

Plugin not appearing in Plugin Manager

Symptom: AgentUX does not appear under Edit > Plugins in the editor.

Cause: The plugin folder is in the wrong location for your build type.

Solution:

• Retail / Epic Games Launcher build: Place the plugin in your project directory:

  <YourProject>/Plugins/AgentUX/

• Source build: Place the plugin in the engine directory:

  <UE Root>/Engine/Plugins/Experimental/AgentUX/

Verify that the folder contains AgentUX.uplugin at the top level. Restart the editor after moving the plugin.

Missing binary files after build

Symptom: The plugin appears in the Plugin Manager but fails to load, with errors about missing DLLs.

Cause: The build did not produce binaries, or the build configuration was incorrect.

Solution:

1. Close the editor completely before building.
2. Run the build command from the engine root:

   Engine/Build/BatchFiles/Build.bat UnrealEditor Win64 Development -Module=AgentUX

3. Confirm that Binaries/Win64/ contains .dll and .modules files after the build completes.
4. For retail builds, ensure "Installed": true is set in AgentUX.uplugin so the engine uses pre-compiled binaries.

.uproject plugin reference not working

Symptom: The editor ignores the plugin entry in the .uproject file.

Cause: The JSON structure is malformed or the plugin name does not match exactly.

Solution: Verify the plugin entry uses the exact name AgentUX (case-sensitive):

{
  "Plugins": [
    { "Name": "AgentUX", "Enabled": true }
  ]
}

Check for JSON syntax errors (trailing commas, missing brackets). The editor silently ignores malformed plugin entries.

Plugin version mismatch with engine version

Symptom: The plugin loads but logs warnings about version incompatibility, or methods behave unexpectedly.

Cause: The plugin binary was compiled against a different engine version.

Solution:

1. Use agentux.ping to verify the reported engine version:

   {"jsonrpc": "2.0", "id": 1, "method": "agentux.ping"}

   The response includes ue_version and plugin_version.
2. Rebuild the plugin from source against your current engine version if the versions do not match.
3. For retail builds, download the binary package that matches your engine version.

Method Errors

"Method not found" responses

Symptom: The server returns a JSON-RPC error with code -32601 ("Method not found").

Cause: The method name is misspelled, uses the wrong case, or is missing the namespace prefix.

Solution:

1. List all available methods:

   {"jsonrpc": "2.0", "id": 1, "method": "agentux.methods.list"}

2. All methods use namespace.method format. For example: editor.state.getSelection, not getSelection.
3. Method names are case-sensitive. editor.state.getselection will not work.
4. If using Claude through the MCP bridge, Claude automatically discovers available methods. If calling directly, always verify names against the method list first.

Parameter validation failures

Symptom: Error response with code -32602 ("Invalid params") even though the method name is correct.

Cause: Required parameters are missing, or parameter types do not match the expected schema.

Solution:

1. Check the API Reference for the exact parameter names and types for that method.
2. Ensure all required fields are present in the params object.
3. Verify type correctness: string IDs must be strings (not integers), coordinates must be numbers (not strings), and boolean flags must be true/false (not 1/0).

Safety guard rejections

Symptom: A mutating method returns an error indicating the operation was blocked by a safety guard.

Cause: Certain operations are blocked when the editor is in a state that could cause data loss or crashes, such as during Play-In-Editor (PIE) sessions or garbage collection.

Solution:

1. Check the current safety status:

   {"jsonrpc": "2.0", "id": 1, "method": "agentux.safety.status"}

2. If PIE is running, stop the play session before attempting editor mutations (spawning actors, modifying properties, etc.).
3. If GC is in progress, wait a moment and retry. Garbage collection typically completes in milliseconds.
4. Read-only methods (queries, state inspection) are never blocked by safety guards.

Timeout on long operations

Symptom: No response received within the expected time for operations like building lighting or importing large assets.

Cause: Some editor operations are inherently slow (lighting builds can take minutes). The default client timeout may be too short.

Solution:

1. Increase your client-side timeout for known slow operations. The server does not time out: it will respond when the operation completes.
2. For batch requests, avoid mixing fast queries with slow operations in the same batch. Send slow operations individually.
3. Monitor progress via the Output Log for operations like editor.build.lighting.

GraphRAG Issues

Neo4j not running or not reachable

Symptom: GraphRAG MCP tools return connection errors referencing bolt://localhost:7687.

Cause: The Neo4j server is not running, or it has not finished starting (the JVM takes several seconds to boot).

Solution:

1. Check Neo4j status:

   neo4j status

2. If stopped, start it:

   neo4j start

3. Wait for the bolt port to accept connections (cold start takes approximately 5.5 seconds):

   netstat -an | findstr 7687

4. For reliable auto-start, install Neo4j as a Windows service:

   neo4j install-service
   neo4j start

5. See the Installation guide for full Neo4j setup instructions.

Slow first query

Symptom: The first semantic search takes 15-20 seconds, while subsequent queries complete in under a second.

Cause: The ONNX embedding model (~600 MB) is lazily loaded on the first semantic query. This is by design to avoid slowing down MCP server startup.

Solution:

• This is expected behavior. After the one-time load, every subsequent query completes in approximately 300 ms.
• If the OS file cache is warm (model was loaded in a previous session), the cold start drops to approximately 4 seconds.
• Structural graph queries (get_class_details, get_class_hierarchy, etc.) do not use embeddings and are fast from the start (4-45 ms).

Stale data after engine update

Symptom: GraphRAG returns information about classes, properties, or modules that no longer exist or are missing newly added ones.

Cause: The knowledge base was built against a previous engine version and needs to be re-indexed.

Solution: Rebuild the knowledge base to reflect your current engine source:

python install.py --skip-deps

This reconfigures credentials, restores the knowledge base, and validates the embedding model. See the GraphRAG Guide for details on the rebuild process.

LanceDB index corruption

Symptom: Vector search returns errors, empty results, or crashes with file-related exceptions.

Cause: The LanceDB vector index files were corrupted, possibly from an interrupted write or disk issue.

Solution:

1. Delete the LanceDB data directory:

   rm -rf <AgentUX>/GraphRAG/lancedb_data/

2. Re-run the installer to rebuild the vector index:

   python install.py --skip-deps

3. Verify by running a semantic search query through Claude or the MCP tools.

MCP Configuration

Claude Code not discovering MCP tools

Symptom: Claude does not offer AgentUX or GraphRAG tools when prompted about Unreal Engine tasks.

Cause: The MCP server configuration is not in the expected location, or the config file has syntax errors.

Solution:

1. Verify the configuration file exists at one of these paths:
   • Project-level: <YourProject>/.claude/settings.json
   • User-level: ~/.claude/settings.json
2. Confirm the mcpServers section includes both the agentux and ue-graphrag entries (or just agentux for editor-only mode). See the Installation guide for the exact format.
3. Restart Claude Code after editing the configuration. MCP settings are read at startup.

MCP server process not starting

Symptom: Claude Code reports that the MCP server failed to start or timed out during initialization.

Cause: The Python or Node.js environment is not configured correctly, or the server script path is wrong.

Solution:

1. Verify that python is on your PATH and is version 3.10+:

   python --version

2. Test the bridge server manually:

   python <path-to>/AgentUX/Bridge/agentux_mcp_bridge.py

   It should start without errors and wait for MCP messages on stdin.
3. If using Bridge v2 (Agent SDK), verify Node.js 20+ is installed:

   node --version

4. Ensure all paths in the MCP config use forward slashes or properly escaped backslashes.

Environment variable issues

Symptom: GraphRAG MCP server starts but cannot connect to Neo4j, or reports missing configuration.

Cause: Required environment variables are missing or point to wrong values.

Solution: Verify the following variables are set in the MCP config's env block:

• GRAPHRAG_CONFIG: must point to the absolute path of config.yaml inside the AgentUX GraphRAG directory.

If Neo4j uses non-default credentials, ensure the config.yaml file contains the correct values for NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD. Running python install.py --skip-deps will auto-detect and write these values.

Editor-only vs full config differences

Symptom: Some AgentUX tools work (editor control) but GraphRAG tools are unavailable, or vice versa.

Cause: The MCP configuration only includes one of the two servers.

Solution:

• Editor control only requires the agentux MCP server entry: this provides 558+ editor methods.
• GraphRAG knowledge requires the ue-graphrag MCP server entry: this provides 20 search/lookup tools.
• For full functionality, include both entries. The bridge auto-detects whether GraphRAG is available and exposes a graphrag_status tool for runtime connectivity checks.

Performance

Cold start times

Symptom: The first WebSocket connection after launching the editor takes noticeably longer than subsequent ones.

Cause: The WebSocket server binds during StartupModule() in approximately 2.5 ms, but the first connection may trigger lazy initialization of certain handler subsystems.

Solution:

• Plugin startup is extremely fast (~3.4 ms total) and should be imperceptible. If you experience multi-second delays, check for other plugins or project-level initialization competing for resources.
• The WebSocket server has zero background resource usage until a client connects: there is no dedicated thread.
• Send an agentux.ping as your first message to warm up the connection before issuing real commands.

Embedding model load time

Symptom: The first GraphRAG semantic search takes approximately 18 seconds.

Cause: The ONNX embedding model (~600 MB) loads on the first semantic query. This is a one-time cost per MCP server session.

Solution:

Structural queries (get_class_details, get_class_hierarchy) bypass the embedding model entirely and are fast from the start.

Large batch request timeouts

Symptom: A batch of many requests times out or takes significantly longer than expected.

Cause: Batch requests are processed sequentially on the editor tick. A batch containing slow operations blocks subsequent items.

Solution:

1. Keep batches to fast, read-only operations for best performance:

   [
     {"jsonrpc": "2.0", "id": 1, "method": "agentux.ping"},
     {"jsonrpc": "2.0", "id": 2, "method": "editor.state.getSelection"},
     {"jsonrpc": "2.0", "id": 3, "method": "editor.state.getWorldInfo"}
   ]

2. Send slow mutating operations (lighting builds, large imports) as individual requests with extended client-side timeouts.
3. The MCP bridge handles batching automatically: this is primarily relevant for direct WebSocket integrations.

Memory usage with many concurrent connections

Symptom: Editor memory usage increases significantly when multiple WebSocket clients are connected.

Cause: Each connection maintains its own message buffer and handler state.

Solution:

• In normal usage (1-3 concurrent connections), memory overhead is negligible.
• If you are running automated test suites with many parallel connections, close idle connections promptly.
• The WebSocket server is pumped via the editor tick loop. Excessive concurrent connections may reduce editor frame rate. Limit concurrent clients to what your workflow requires.

Diagnostic Quick Reference

Use these JSON-RPC calls to quickly assess the system state when troubleshooting:

Still Stuck?

• Check the Installation page for setup requirements and step-by-step instructions.
• Review the Getting Started guide for a working end-to-end walkthrough.
• Consult the GraphRAG Guide for knowledge base tool reference and query patterns.
• Search the Output Log for LogAgentUX messages: the plugin logs detailed diagnostics at startup and on errors.