Common Errors & Fixes

Swarm: Couldn’t reach cloud save

Your canvas is still backed up in the browser (fuseiq_swarm_autosave). Cloud save writes a workflow definition plus nodes/edges.

• Retry with ⌘S / Ctrl+S after a hard refresh
• If you see rate-limit text, wait a few seconds and save again
• If session expired, sign in again — local backup remains until cleared

Knowledge Vault: embeddings unavailable

Search fails closed when no embedding key is available (we never invent fake vectors).

• Add an OpenAI key under Settings → AI Providers (or platform OPENAI_API_KEY)
• Retry search after the key saves

Eval Studio: not available (503)

Eval returns a hard error if framework tables are missing — not an empty green success. Contact support if this persists on production; it should not appear when schema is healthy.

Integration shows not_configured

Amazon Seller, Etsy, eBay, Instagram, and TikTok require platform OAuth secrets. Without them the badge is honest — not Live. Use Universal HTTP / Custom Connector where possible.

404 Page Not Found

If you hit a 404 after login, it's usually a role-based access issue. The page exists but your role doesn't have permission.

• Members cannot access /billing, /approvals, or /team
• Viewers can only access /staff and /chat
• If you need access, ask your Director to upgrade your role

Agent Offline (Red Indicator)

• Check your agent's heartbeat URL — must be accessible from the internet
• Verify the API key is correct and not expired
• Ensure your agent sends a heartbeat every 15 seconds
• Check firewall rules — ports 443 and 80 must be open

Messages Not Loading

• Hard refresh (Cmd/Ctrl + Shift + R)
• Check browser console for CORS errors
• Verify Supabase Realtime is enabled in your project settings
• Try switching to another conversation and back

Chat Hub: Agent failed (actions column)

If you see Could not find the 'actions' column of 'messages', the Chat Hub integration-approval migration has not been applied yet. Agent replies still work — only inline action buttons are affected.

• Retry after the platform migration runs (automatic on deploy)
• Hard refresh Chat Hub after upgrading
• Contact support if the error persists beyond 24h after a release

Billing Plan Not Updating

• Paddle webhooks can take 1-2 minutes to process
• Clear browser cache and refresh
• Check Paddle dashboard for subscription status
• If stuck for >10 minutes, contact support with your workspace ID

Realtime Notifications Not Working

• Check that Supabase Realtime is enabled (project-level toggle)
• Verify the messages table has a Realtime publication
• Ensure RLS policies allow SELECT on notifications table
• Try logging out and back in to refresh the auth token