Skip to main content

Troubleshooting Guide

Status

Owner: TBD · Status: draft · Canonical source: flezi.docs

Solutions for common operational and client issues.

1. Chat screen freezes or displays "Stream Disconnected"​

  • Cause: Intermittent network interruption or proxy connection timeout.
  • Resolution: Reload the browser tab. The client automatically replays all streamed tokens from the Redis Stream cursor (Last-Event-ID).

2. "403 Forbidden" error when clicking an action​

  • Cause: Your assigned role in the active workspace does not possess sufficient authority.
  • Resolution: Confirm you are operating within the correct workspace, or ask your Workspace Admin to adjust your role.

3. Skill Recorder extension fails to connect​

  • Cause: The web application session expired or extension authorization was not granted.
  • Resolution: Navigate to /authorize on the web portal and re-click Authorize Extension.

4. MCP Connector shows Needs OAuth or Test Connection times out​

  • Needs OAuth: Open Account & OAuth, authorize the current account, then run Test Connection again. Sharing a connector does not share OAuth tokens.
  • Test timeout: Check the MCP endpoint and transport. Tool discovery is bounded at 30 seconds; a server that never lists tools fails instead of hanging the run.
  • STDIO command not found: The command must be installed in the service runtime and visible on its service PATH, not only in an interactive terminal.
  • OAuth returns to the UI but is not Connected: Only oauth_result=success confirms the callback; mcp_connected=1 alone is not sufficient.