Skip to main content

Troubleshooting

Common issues and how to fix them. If your problem is not listed here, reach out at [email protected].

CLI won't connect

The CLI needs outbound HTTPS (port 443) to styrbyapp.com and supabase.co.

Check connectivity

curl -I https://styrbyapp.com/api/health
# Should return HTTP 200

curl -I https://supabase.co
# Should return HTTP 200

Firewall or proxy

If you are behind a corporate firewall or proxy, set the standard proxy environment variables:

export HTTPS_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1

VPN issues

Some VPNs intercept WebSocket connections. If styrby status shows "connecting" indefinitely, try disconnecting your VPN temporarily to confirm.

"Not authenticated" error

Run the full setup wizard to authenticate and register your machine:

styrby onboard
# Use --force to re-authenticate if already set up
styrby onboard --force

Agent not appearing in the dashboard

  1. Run the health check to see if your agent is detected: 
    styrby doctor
  2. If the agent shows as "not installed", install it:
    styrby install claude
  3. Confirm the CLI is running and connected:
    styrby status
  4. Start the agent via Styrby (not directly):
    styrby claude
  5. Check CLI logs for errors:
    STYRBY_LOG_LEVEL=debug styrby status

Push notifications not working

  • Check OS permissions:Make sure the Styrby app has notification permission in your phone's settings.
  • Check quiet hours:Notifications are suppressed during quiet hours (except permission requests). Verify your quiet hours config in Settings > Notifications.
  • Token registration: Force a token refresh by signing out of the mobile app and signing back in. This re-registers the push token (APNs or FCM).
  • Check event types: Make sure the specific event type is enabled in your notification preferences.

Cost data delayed or missing

The daily cost chart uses a materialized view (mv_daily_cost_summary) that refreshes periodically for performance. If you just finished a session:

  • Near real-time cost data appears in session detail views and the cost ticker.
  • The daily aggregate chart updates within 5 minutes when the materialized view refreshes.
  • If data is still missing after 10 minutes, check your machine connection status. Cost records require the CLI to be online to report.

Session replay shows blank messages

Session messages are end-to-end encrypted. Blank messages mean the decryption key on your current device does not match the key used to encrypt the session.

Common causes

  • Different device: You are viewing from a device that was not paired when the session was recorded. Each device has its own keypair.
  • Re-onboarded: If you ran styrby onboard --force after the session was recorded, a new keypair was generated. Sessions encrypted with the old key are no longer decryptable on this machine.
  • Cleared config: If ~/.styrby/config.json was deleted, the private key was lost along with it.

Fix

Open the session from the original machine where the agent ran. That machine has the private key in ~/.styrby/config.json and can decrypt the session.

Voice Input