{"slug":"connectors/ONBOARDING_CONNECTORS_ERROR","title":"Troubleshooting: \"Failed to load connectors\" in Onboarding","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/ONBOARDING_CONNECTORS_ERROR.mdx","bytes":4997,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Issue**: Onboarding flow shows \"Failed to load connectors\" error at Step 4  \n> **Date**: 2026-05-29  \n> **Status**: Fixed with fallback mechanism\n\n---\n\n## Problem\n\nUsers see \"Failed to load connectors\" error during onboarding at the Connectors step (Step 4 of 4-screen flow).\n\n### Error Details\n\n```\nFailed to load connectors\nRetry\n```\n\n### Root Cause\n\nThe onboarding flow calls `/api/v1/workspace/connectors` which routes through:\n\n```\nFrontend → Gateway → BFF (workflow service) → getWorkspaceConnectors()\n```\n\nPossible failure points:\n\n1. **BFF service not deployed** — `integratewise-bff` Worker not running\n2. **Service binding missing** — Gateway doesn't have BFF binding configured\n3. **Network timeout** — BFF service taking too long to respond\n4. **Spine DB connection failure** — BFF can't read tenant config\n5. **Catalog function error** — `getSerializableCatalog()` throws exception\n\n---\n\n## Solution Implemented\n\n### 1. Fallback Mechanism (Frontend)\n\nAdded automatic fallback to `/api/v1/connectors/catalog` if BFF endpoint fails:\n\n```typescript\n// Try workspace endpoint first (BFF service)\ntry {\n  const data = await apiFetch(\"/api/v1/workspace/connectors\");\n  setCatalog(data.connectors || []);\n} catch (err) {\n  // Fallback to connector catalog endpoint if BFF is unavailable\n  try {\n    const fallbackData = await apiFetch(\"/api/v1/connectors/catalog\");\n    setCatalog(fallbackData.connectors || []);\n  } catch (fallbackErr) {\n    setError(\"Failed to load connectors. Please check your network connection...\");\n  }\n}\n```\n\n### 2. Improved Error UI\n\nEnhanced error state with:\n\n- Clear error message\n- Retry button\n- Skip button (allows user to continue without connectors)\n- Helpful hint about connecting tools later\n\n---\n\n## Verification Steps\n\n### 1. Check BFF Service Status\n\n```bash\n# Check if BFF Worker is deployed\nwrangler deployments list --name integratewise-bff\n\n# Test BFF endpoint directly\ncurl https://gateway.integratewise.ai/api/v1/workspace/connectors \\\n  -H \"Authorization: Bearer <JWT>\" \\\n  -H \"x-tenant-id: <tenant-id>\"\n```\n\n### 2. Check Gateway Service Binding\n\n```bash\n# Verify BFF binding exists in Gateway wrangler.toml\ngrep -A 2 \"binding = \\\"BFF\\\"\" services/gateway/wrangler.toml\n\n# Expected output:\n# [[services]]\n# binding = \"BFF\"\n# service = \"integratewise-bff\"\n```\n\n### 3. Check Connector Catalog Fallback\n\n```bash\n# Test fallback endpoint\ncurl https://gateway.integratewise.ai/api/v1/connectors/catalog \\\n  -H \"Authorization: Bearer <JWT>\" \\\n  -H \"x-tenant-id: <tenant-id>\"\n```\n\n---\n\n## Deployment Checklist\n\nTo prevent this error:\n\n- [ ] Deploy BFF Worker: `cd services/workflow && wrangler deploy --env production`\n- [ ] Verify Gateway has BFF service binding in wrangler.toml\n- [ ] Verify BFF Worker has all required bindings:\n  - `SPINE_URL`\n  - `SPINE_ANON_KEY`\n  - Service bindings: `SPINE`, `CONNECTOR`, `KNOWLEDGE`, `THINK`, `ACT`\n  - D1 binding: `ANALYTICS_DB`\n  - KV bindings: `CONNECTION_META`, `RATE_LIMIT`\n- [ ] Test onboarding flow end-to-end\n- [ ] Verify fallback mechanism works (temporarily disable BFF to test)\n\n---\n\n## Monitoring\n\n### Key Metrics to Watch\n\n1. **Connector Load Success Rate**\n   - Track: `onboarding_connectors_loaded` vs `onboarding_connectors_failed`\n   - Alert if failure rate > 5%\n\n2. **BFF Service Health**\n   - Track: `/api/v1/workspace/connectors` response time\n   - Alert if p95 > 2s or error rate > 1%\n\n3. **Fallback Usage**\n   - Track: How often fallback endpoint is used\n   - High fallback usage indicates BFF reliability issues\n\n### Logging\n\n```typescript\n// Frontend logs (check browser console)\n[ConnectorsStep] Both endpoints failed: {\n  primary: Error(\"Failed to load connectors\"),\n  fallback: Error(\"Network error\")\n}\n\n// BFF logs (check Cloudflare Workers logs)\n[BFF] getWorkspaceConnectors error: <error details>\n```\n\n---\n\n## Related Files\n\n- **Frontend**: `/apps/web/src/components/activation/onboarding/steps/ConnectorsStep.tsx`\n- **BFF Service**: `/services/workflow/src/index.ts` (getWorkspaceConnectors function)\n- **Gateway Routing**: `/services/gateway/src/index.ts` (routes /api/v1/workspace/\\* to BFF)\n- **Connector Catalog**: `/services/connector/src/index.ts` (fallback endpoint)\n\n---\n\n## Future Improvements\n\n1. **Retry with Exponential Backoff**\n   - Automatically retry failed requests 2-3 times before showing error\n\n2. **Offline Mode**\n   - Cache connector catalog in localStorage\n   - Show cached data if API fails\n\n3. **Progressive Enhancement**\n   - Load connectors in background while showing skeleton UI\n   - Allow user to proceed even if connectors haven't loaded yet\n\n4. **Better Error Messages**\n   - Distinguish between network errors, auth errors, and service errors\n   - Provide specific troubleshooting steps based on error type\n\n---\n\n**Document Version**: 1.0  \n**Last Updated**: 2026-05-29  \n**Author**: Kiro (Troubleshooting Guide)  \n**Status**: Fixed — Fallback mechanism deployed\n"}