Documentation Portal

Troubleshoot the bridge by following the current contracts, not guesses.

These scenarios are pulled from the implemented bridge behavior and operator guides: readiness checks, persisted-but-offline sessions, auth-lane mismatches, policy denials, and MCP transport rejections.

Documentation map

The docs portal stays in the same application as the product shell so setup, deployment, connector, and developer guidance can evolve with the codebase.

In-repo docs7 foundation routes5 developer routesCurrent: Troubleshooting

Foundation docs

  • OverviewRoute

    Start with the current architecture, product surfaces, and the stable documentation sections.

  • Getting StartedRoute

    Install the workspace, configure local env files, and run the first verification flow.

  • DeploymentRoute

    Use the managed bridge deployment order, health checks, migrations, and workspace bootstrap flow.

  • ConnectorsRoute

    Understand the Figma reference connector, Satellite runtime, and explicit session routing model.

  • SecurityRoute

    Review auth lanes, workspace isolation, policy controls, rate limiting, and audit semantics.

  • API ReferenceRoute

    Browse the stable HTTP route groups, shared envelopes, auth lanes, and machine-readable errors.

  • TroubleshootingOpen

    Use the current operational failure patterns for readiness, auth, session liveness, policy, and MCP issues.

Developer docs

  • DevelopersRoute

    Developer-facing entry point for HTTP, MCP, connector, and shared-contract guidance.

  • Developer QuickstartRoute

    Bring up the bridge, connect one runtime, and make the first explicit authenticated calls.

  • HTTP GuideRoute

    Use the bridge HTTP transport with the correct auth lane, shared envelopes, and explicit targetSessionId routing.

  • MCP GuideRoute

    Use the Streamable HTTP MCP endpoint, LIST_CAPABILITIES, and the same connector-neutral tool catalog.

  • Connector ModelRoute

    Understand connector definitions, capability metadata, data scopes, and high-risk policy presets.

Current failure patterns

Treat the symptom first, then verify the explicit route, auth, and runtime constraints that the bridge already exposes.

Readyz fails with SERVICE_UNAVAILABLE

Checklist

Symptom: The bridge process responds, but /readyz does not return HTTP 200.

  • Confirm Postgres and Redis values still match the active deployment env contract.
  • Treat /readyz, not /healthz, as the deploy gate before routing traffic.
  • After secret changes such as SUPABASE_DB_URL or REDIS_URL, restart or redeploy the bridge.

A session exists but the runtime is not actually live

Checklist

Symptom: GET /api/v1/sessions/:sessionId returns HTTP 200, but the target runtime cannot execute.

  • Require session.runtimeHealth.status = online before treating the runtime as a valid smoke target.
  • Keep the Figma plugin window open or reconnect the Satellite runtime after restart or redeploy.
  • Do not treat persisted session detail alone as proof that the live socket is still connected.

Auth succeeds in one lane and fails in another

Checklist

Symptom: Human shell reads work, but API-key execution fails, or the inverse.

  • Use a Supabase bearer token only for GET /api/v1/account/session and secure human routes.
  • Use Authorization: Bearer <api-key> for GET /api/v1/tools, POST /api/v1/tools/execute, and POST /mcp.
  • When calling workspace-scoped discovery routes as a human user, include x-uab-workspace-id.

Execution is denied before the runtime sees the request

Checklist

Symptom: The bridge returns CAPABILITY_DENIED, DATA_SCOPE_DENIED, or RATE_LIMITED.

  • Inspect /app/workspace/policies, /app/workspace/capabilities, or /app/workspace/data-scopes for the current workspace rule state.
  • Remember that high-risk Satellite execute paths stay fail-closed until an explicit allow rule exists.
  • Treat rate limiting as workspace-scoped infrastructure protection rather than connector failure.

MCP requests are rejected before tool execution

Checklist

Symptom: POST /mcp returns a JSON-RPC error without reaching the shared controller.

  • Send API-key bearer auth to the MCP endpoint just like the HTTP execution lane.
  • Preserve valid JSON-RPC request structure and MCP-compatible content negotiation headers.
  • If the authenticated workspace does not match the provided workspaceId, the transport rejects the request before execution.

Operational guardrails

These are the checks that prevent the most common false positives during deployment and smoke work.