AgentUX Support

Browse common issues by category or contact us for help. The AgentUX support skill (/skill customer-support) can also diagnose issues interactively.

On This Page

Installation

DLL not found on editor startup

Symptom: Plugin fails to load. Output Log shows "Module AgentUX could not be loaded" or "Missing DLL".

Cause: DLL not present in Binaries/Win64/, or BuildId mismatch between DLL and your UE install.

Solution: Verify AgentUX.dll exists in Engine/Plugins/AgentUX/Binaries/Win64/. Check that the .modules file BuildId matches your UE install. Re-download the plugin package if mismatched.

Python dependency conflict during install

Symptom: pip install fails with version conflict errors when setting up MCP bridge or GraphRAG.

Cause: System Python has conflicting package versions, or Python version too old (requires 3.10+).

Solution: Create a fresh virtual environment:

python -m venv .venv
.venv/Scripts/activate
pip install -r requirements.txt

Connection

Port 9877 already in use

Symptom: WebSocket server fails to start. Output Log shows bind error on port 9877.

Cause: Another editor instance or stale process is holding the port.

Solution: Find the process with netstat -ano | findstr 9877, then close the other editor or kill the stale process. Only one AgentUX server can bind to port 9877 at a time.

WebSocket connection rejected silently

Symptom: Client connects but is immediately disconnected with no error message.

Cause: Auth token not set in credential store, or client not calling agentux.auth before other JSON-RPC methods.

Solution: Set the auth token in AgentUX Settings (Window > Tools > AgentUX). After the WebSocket handshake succeeds, the client's first JSON-RPC call MUST be agentux.auth with { "token": "<value>" } in params. Subsequent calls on the same connection proceed as authenticated. Calling any other method first returns AuthRequired.

Handler Errors

Error -32004 UnsafeState during PIE

Symptom: Mutating method call returns error code -32004 while Play-in-Editor is active.

Cause: SafetyOracle blocks mutating calls during PIE to prevent editor crashes. This is by design.

Solution: Stop PIE (editor.pie.stop) before calling mutating methods. Wait 2 seconds after stop for state to settle. Read-only methods work during PIE.

Error -32001 method not found

Symptom: JSON-RPC call returns error code -32001.

Cause: Method name misspelled, wrong namespace, or handler not registered. Names are case-sensitive.

Solution: Call agentux_methods_list to see all registered methods. Common mistake: use editor.actor.spawn (lowercase namespace), not editor.Actor.spawn.

GraphRAG / Neo4j

Neo4j connection refused

Symptom: GraphRAG tools return errors. agentux_graphrag_status shows Neo4j unreachable.

Cause: Neo4j service not running, wrong port, or firewall blocking local connections.

Solution: Start Neo4j with neo4j console (or neo4j start for service mode). Verify the bolt port in neo4j.conf (default 7687). Check that credentials in OS keyring match the Neo4j password.

Queries return zero results

Symptom: search_ue_source, get_class_details, and other tools return empty despite Neo4j being connected.

Cause: Knowledge base not imported, or wrong database selected.

Solution: Run agentux_graphrag_status to check node count. If zero, run install.py to restore the curated knowledge base. Verify config.yaml points to the correct database.

Performance

Error -32006 rate limit exceeded

Symptom: Rapid API calls return error code -32006 after approximately 100 requests.

Cause: Default rate limit is 100 requests per second per connection.

Solution: Increase MaxRequestsPerSecond in AgentUX Settings (default 100, max 1000). Alternatively, use the batch API (editor.batch) to combine multiple calls into one request.

Large responses cause timeout

Symptom: Methods like agentux_methods_list or large asset queries take very long or appear truncated.

Cause: Response size exceeds Claude context window or WebSocket frame size.

Solution: Use limit parameters where available. For methods_list, filter by namespace. For asset queries, narrow the search path.

Bridge / MCP

MCP bridge subprocess exits unexpectedly

Symptom: Bridge process starts then immediately exits. Claude Code shows "MCP server disconnected".

Cause: Missing Python dependencies, invalid config.yaml, or API key not in credential store.

Solution: Run the bridge manually to see error output: python Bridge/agentux_mcp_bridge.py. Check that config.yaml exists and is valid YAML. Verify the Anthropic API key is in the OS credential store.

Invalid model ID error

Symptom: Model selector shows error or bridge rejects model selection.

Cause: Using dated model ID format (API-only) instead of undated format (CLI-compatible).

Solution: Use undated model IDs like claude-sonnet-4-6, not claude-sonnet-4-6-20251101. The bridge and CLI require the short form.

Authentication

Credential store empty on first run

Symptom: First-time setup fails because no API key or auth token is configured.

Cause: AgentUX uses the OS credential store (Windows Credential Manager / macOS Keychain), not environment variables.

Solution: Open AgentUX Settings (Window > Tools > AgentUX). Enter your Anthropic API key and generate an auth token. The plugin stores these in the OS credential manager automatically.

Auth token rejected despite being set

Symptom: WebSocket connection fails with auth error even though the token is configured.

Cause: Token mismatch: client sending a malformed token, wrong token value, or token with trailing whitespace/newline in the agentux.auth call.

Solution: Pass the token as a plain string in the agentux.auth params object: { "method": "agentux.auth", "params": { "token": "<value>" } }. Strip leading/trailing whitespace client-side. Regenerate the token in Settings if in doubt.

Edition & Tier Questions

Why does Free show tips about the knowledge base?

Symptom: Occasional tips about GraphRAG appear when a method returns an error on Free.

Cause: Free ships the full editor-control surface and surfaces informational hints about what Pro adds on top. The tips are advisory, not gating -- no functionality is blocked.

Solution: Free is fully functional. All 45 handlers and 662 methods work identically on every tier (662 on UE 5.7+; 577 on UE 5.6). Upgrade to Pro when your AI could use engine-knowledge queries, version-aware API diffs, or accumulated session experience. Tips stop appearing once GraphRAG is detected locally.

Why does a GraphRAG MCP tool return an upgrade message?

Symptom: Calling a GraphRAG MCP tool (like get_class_details or search_ue_source) returns an upgrade response instead of results.

Cause: The GraphRAG MCP tools are the Pro knowledge-layer surface. They remain visible on Free so your AI can discover what Pro adds, but they return an advisory response pointing at the upgrade path rather than querying the knowledge graph.

Solution: See the Pricing page for edition comparison and upgrade paths. If you already have Pro, check config.yaml mcp.tier and verify the installer completed the Neo4j and knowledge base setup.

Contact Support

If your issue is not covered above, you can get help in two ways:

Interactive Diagnosis

Run the AgentUX support skill in Claude Code:

/skill customer-support

The skill collects system information, runs targeted diagnostics, and generates a structured report you can send to support.

Email Support

Send your issue description and any diagnostic output to:

support@williamscloudtechnology.com

Include: your AgentUX version, UE version, OS, and any error messages or codes.

For detailed technical troubleshooting steps, see the Troubleshooting Guide.