Troubleshooting

Authentication Errors

GguiAuthError: Authentication failed

• Verify your API key starts with ggui_sk_ and is complete (no truncation)
• Check that you’re using the correct key for your environment
• Regenerate your API key from the ggui dashboard if needed

WebSocket 401 Unauthorized

• Verify wsEndpoint in GguiProvider uses wss:// not https://
• Check that the user’s authentication token is valid and not expired

---

Connection Issues

WebSocket stuck on 'reconnecting'

• The SDK uses exponential backoff (1s → 30s) and retries 10 times
• After 10 failed attempts, reconnection stops — remount the GguiSession component to restart
• Check if your network blocks WebSocket traffic (some corporate firewalls do)

Events lost during disconnection

The EventBuffer holds up to 100 messages during disconnection. For critical submissions, check connectionStatus before allowing submit:

{
  ({ submit, connectionStatus }) => (
    <button onClick={() => submit(data)} disabled={connectionStatus !== "connected"}>
      Submit
    </button>
  );
}

---

Session Errors

GguiSessionNotFoundError: Session not found

• Sessions expire after a period of inactivity — create a new session
• waitForCompletion handles this gracefully and returns collected events
• Verify you’re using the correct environment (sandbox vs production sessions are separate)

---

Component Rendering Errors

Module does not export a default function component

• Verify the componentCode from the stack item is valid ESM with a default export
• Check the UI Generator logs for compilation errors

Component shows red error border

Use onError prop for custom error handling:

<StackItemRenderer
  stackItem={item}
  onError={(error) => console.error("Render failed:", error)}
  fallback={<div>Loading...</div>}
/>

Stale component after code update

Clear the module cache:

import { clearModuleCache } from "@ggui-ai/react";
clearModuleCache();

---

Tool System Errors

Tool "X" not registered

Built-in tools are auto-registered on import. Ensure you import @ggui-ai/react.

Circular dependency detected

Review your dependsOn declarations and break the cycle. Dependencies must form a DAG (directed acyclic graph).

---

MCP Protocol Errors

Code	Meaning	Common Cause
-32700	Parse error	Malformed JSON
-32600	Invalid request	Missing required fields
-32602	Invalid params	Wrong types or missing params
-32001	Unauthorized	Invalid API key
-32002	Session not found	Expired or deleted session
-32004	Generation failed	UI generation failed on server

Generation timeout

Increase the timeout or simplify the prompt:

const ggui = new GguiClient({
  apiKey: "ggui_sk_...",
  appId: "app_...",
  timeout: 60000, // 60 seconds
});

---

Debugging Tips

• Network tab: Check WebSocket frames and HTTP requests to the MCP endpoint
• Console: Look for errors from DynamicComponent, SelfRepairBoundary, and the tool system
• Validate bindings: validateBindings(myBindings) checks for issues before rendering
• Check tool registry: toolRegistry.getRegisteredNames() lists all registered tools