Networking & API Access

Quick checks

Before investigating specific issues, try these general steps:

1. Check platform health. curl https://www.ivybiosciences.com/api/health returns the status of the database, storage and cache checks, and it needs no sign-in. When you're signed in, the /health page shows the same checks.
2. Try an incognito window. This rules out interference from extensions.
3. Disable VPN/proxy temporarily. If the issue disappears, your VPN or proxy is the cause.
4. Try a different network. Switch from corporate Wi-Fi to a mobile hotspot to isolate network-level issues.

WebSocket connection failures

Job progress comes from the compute orchestrator over WebSocket, but the browser doesn't open that WebSocket. The server holds it and relays each job's events to the workspace as an SSE (Server-Sent Events) stream on this site, /api/v1/jobs/[jobId]/events. SSE runs over ordinary HTTPS, so a proxy that blocks WebSocket upgrades doesn't affect the workspace.

A WebSocket connection to 'wss://...' failed error in the console therefore comes from your own script or an extension, not from the workspace. If you connect to the orchestrator's WebSocket yourself (see WebSocket streaming) and it fails:

If the SSE stream is blocked:

• The workspace falls back to polling job status, so updates arrive more slowly.
• Symptoms: job status only changes after a delay or a reload. Allowlist long-lived HTTPS responses from www.ivybiosciences.com (see the proxy table below).

SSE streaming interrupted

Network conditions can interrupt the SSE streams used for chat and job events.

Symptoms:

• Chat response stops mid-sentence and resumes after a pause.
• A job's status jumps straight from a queued state to a finished one, skipping the intermediate updates.
• Browser console shows EventSource errors.

Reconnection behavior:

• The job event stream sends a heartbeat about every 15 seconds and closes after about 5 minutes, and the client then opens a new one.
• A new stream doesn't replay the events you missed. The client reads the job's current state instead, so the final status is still correct.

Reducing interruptions:

• Avoid switching networks (Wi-Fi to cellular, VPN connect/disconnect) while a response is streaming.
• If on a laptop, prevent sleep during long-running operations.
• Close bandwidth-intensive applications (video calls, large downloads) that compete for the connection.

Corporate proxy setup

Many corporate networks route all traffic through an HTTP proxy. The platform works through most proxies, but some configurations cause issues.

Proxy requirements for the platform:

Self-signed certificates and TLS inspection:

• Some corporate proxies inspect TLS by re-signing traffic with their own CA certificate ("SSL bumping" or "HTTPS interception").
• If your proxy does this, you may see certificate warnings or ERR_CERT_AUTHORITY_INVALID errors.
• Ask your IT team to either bypass TLS inspection for *.ivybiosciences.com or install the proxy's CA certificate in your browser's trust store.

Proxy authentication:

• If your proxy requires authentication, your browser should prompt for credentials.
• For scripts and the CLI, set the HTTP_PROXY and HTTPS_PROXY environment variables, with credentials if needed: http://user:[email protected]:8080.

VPN interference

VPN connections can interfere with the platform in several ways.

Split tunneling:

• With a full tunnel, all traffic, including the platform's, goes through the VPN's network. This adds latency and may add firewall restrictions.
• If split tunneling is available, route *.ivybiosciences.com traffic directly instead of through the VPN tunnel.

DNS resolution through VPN:

• Some VPNs override DNS resolution. If the VPN's DNS server can't resolve ivybiosciences.com, connections fail.
• Run nslookup www.ivybiosciences.com with and without the VPN connected. If the results differ or the VPN returns NXDOMAIN, the VPN's DNS is the issue.
• Ask your IT team to add ivybiosciences.com to the VPN's DNS configuration.

MTU issues:

• VPN tunnels reduce the effective MTU (Maximum Transmission Unit). If packets are too large, they may be dropped silently, which stalls connections.
• Symptoms: file uploads hang at a certain percentage, large API responses never complete.
• Fix: reduce the MTU on your local interface. On macOS: sudo ifconfig en0 mtu 1400. On Linux: sudo ip link set dev eth0 mtu 1400.

API rate limits

The API applies a rate limit to each route class. When you exceed one, it returns HTTP 429 Too Many Requests.

Handling 429 responses:

• The response includes a Retry-After header with the number of seconds to wait before retrying.
• Back off exponentially: wait Retry-After seconds, then twice that, then four times that if later attempts also receive 429.
• Don't retry immediately in a tight loop.

Per-endpoint limits and header details are in Rate limits and API & SDK issues.

Offline mode

The platform needs a network connection. Its service worker coordinates tabs and broadcasts online/offline status, but it doesn't cache pages or API responses.

While you're offline:

• A page that is already open keeps showing what it has loaded.
• You can't send chat messages, submit jobs, fetch new data, or sign in.
• Job status stops updating.

Reconnection:

• When you come back online, reload the page to resync chats and job status. Jobs keep running on the server while you're offline.

CORS issues (self-hosting)

If you are self-hosting the platform, CORS (Cross-Origin Resource Sharing) errors are common during initial setup.

Symptoms:

• Browser console shows Access-Control-Allow-Origin errors.
• API calls from the frontend fail with "CORS policy" messages.
• Preflight OPTIONS requests return 403 or no CORS headers.

Fixing CORS for self-hosting:

1. Next.js API routes. The allowed origins are a fixed list in src/middleware/helpers/corsHelpers.ts and src/middleware/handlers/routeHandlers.ts. They are not read from an environment variable. Add your frontend origin to both lists and redeploy.
2. Storage (Amazon S3). Browser uploads go straight to the S3 bucket, so the bucket needs a CORS rule that allows PUT and GET from your frontend origin. The rule is generated from src/config/s3Cors.ts by npm run build:s3-cors.

DNS resolution

If the platform is completely unreachable (not just slow), DNS resolution may be the issue.

Diagnosis:

• Run nslookup www.ivybiosciences.com or dig www.ivybiosciences.com from your terminal.
• If the lookup fails or returns a wrong IP, your DNS resolver may be misconfigured, blocked, or poisoned.

Fixes:

• Try a public DNS resolver: Google (8.8.8.8), Cloudflare (1.1.1.1), or Quad9 (9.9.9.9).
• If you are on a corporate network, ask IT whether ivybiosciences.com is blocked at the DNS level.
• Flush your local DNS cache: macOS: sudo dscacheutil -flushcache. Windows: ipconfig /flushdns. Linux: sudo resolvectl flush-caches.

Custom domains (self-hosting):

• If you run the platform on a custom domain, check that your DNS records (A, CNAME) point to the correct server.
• A record change reaches most resolvers within the old record's TTL, and can take up to 48 hours everywhere.

Time skew

A wrong system clock can invalidate authentication tokens.

• Clerk session tokens carry iat (issued at) and exp (expires) timestamps and are short-lived. If your system clock is far off, tokens are rejected as expired or not yet valid.
• Sync your system time via NTP. On macOS: System Settings then General then Date & Time, enable "Set date and time automatically." On Linux: sudo timedatectl set-ntp true.
• If you can't sync time (air-gapped network), sign-in will keep failing. Contact support.

Ticket checklist

If you need to contact support about a network issue:

• Endpoint URL and HTTP method
• Full response status code and body snippet (omit API keys and tokens)
• Timestamp, organization slug, and whether VPN or proxy was active
• Results of nslookup www.ivybiosciences.com from your machine
• Whether the issue reproduces on a different network (mobile hotspot)
• Browser DevTools Network tab export (HAR file) if possible