electric-debugging

This skill builds on electric-shapes and electric-proxy-auth. Read those first. # Electric — Debugging Sync Issues ## Setup Enable debug logging to see retry and state machine behavior: ```ts import { ShapeStream, FetchError } from '@electric-sql/client' const stream = new ShapeStream({ url: '/api/todos', backoffOptions: { initialDelay: 1000, maxDelay: 32000, multiplier: 2, debug: true, // Logs retry attempts }, onError: (error) => { if (error instanceof FetchError) { console.error(`Sync error: ${error.status} at ${error.url}`, error.json) } return {} // Always return {} to retry }, }) ``` ## Core Patterns ### Error retry behavior | Error | Auto-retry? | Action | | --------------------- | -------------------------- | ------------------------------------------------------------- | | 5xx server errors | Yes (exponential backoff) | Wait and retry | | 429 rate limit | Yes (respects Retry-After) | Wait and retry | | Network errors | Yes (exponential backoff) | Wait and retry | | 4xx (non-429) | No | Calls `onError` — return `{}` to retry manually | | 409 shape expired | Yes (automatic reset) | Client resets and refetches | | `MissingHeadersError` | Never | Fix CORS/proxy — not retryable even if `onError` returns `{}` | ### Diagnosing MissingHeadersError This error means Electric response headers (`electric-offset`, `electric-handle`) are being stripped, usually by CORS: ``` MissingHeadersError: This is often due to a proxy not setting CORS correctly so that all Electric headers can be read by the client. ``` Fix: expose Electric headers in proxy CORS configuration: ```ts headers.set( 'Access-Control-Expose-Headers', 'electric-offset, electric-handle, electric-schema, electric-cursor' ) ``` ### Diagnosing fast-loop detection Console message: "Detected possible fast loop" with diagnostic info. Cause: proxy/CDN cache key doesn't include `handle` and `offset` query params, so the client gets the same stale response repeatedly. Fix: ensure your proxy/CDN includes all query parameters in its cache key. For Vercel, add to `vercel.json`: ```json { "headers": [ { "source": "/api/(.*)", "headers": [ { "key": "CDN-Cache-Control", "value": "no-store" }, { "key": "Vercel-CDN-Cache-Control", "value": "no-store" } ] } ] } ``` ## Common Mistakes ### HIGH Proxy or CDN not including query params in cache key Wrong: ```nginx # nginx caching without query params in key proxy_cache_key $scheme$host$uri; ``` Correct: ```nginx # Include query params (handle, offset) in cache key proxy_cache_key $scheme$host$request_uri; ``` Fast-loop detection fires after 5 requests in 500ms at the same offset. The client auto-clears caches once, then applies backoff, then throws after 5 consecutive detections. Source: `packages/typescript-client/src/client.ts:929-1002` ### HIGH SSE responses buffered by proxy Wrong: ```nginx location /v1/shape { proxy_pass http://electric:3000; # Default: proxy_buffering on — SSE responses delayed } ``` Correct: ```nginx location /v1/shape { proxy_pass http://electric:3000; proxy_buffering off; } ``` For Caddy: ``` reverse_proxy localhost:3000 { flush_interval -1 } ``` Nginx and Caddy buffer responses by default, causing long delays for SSE live updates. Disable buffering for Electric endpoints. Do NOT disable caching entirely — Electric uses cache headers for request collapsing. Source: `website/docs/guides/troubleshooting.md:69-109` ### MEDIUM Running 6+ shapes in local dev without HTTP/2 Wrong: ```sh # Running Electric directly on localhost:3000 # With 7+ shapes, browser HTTP/1.1 queues all requests (6 connection limit) ``` Correct: ```sh # Run Caddy as HTTP/2 proxy on host (not in Docker — Docker prevents HTTP/2) caddy run --config - --adapter caddyfile <<EOF localhost:3001 { reverse_proxy localhost:3000 } EOF ``` Browser HTTP/1.1 limits to 6 TCP connections per origin. With many shapes, requests queue behind each other. Use Caddy as a local HTTP/2 proxy. Source: `website/docs/guides/troubleshooting.md:28-53` ### HIGH Leaving replication slot active when Electric is stopped Wrong: ```sh docker stop electric # Replication slot retains WAL indefinitely — disk fills up ``` Correct: ```sh docker stop electric # Drop slot when stopping for extended periods psql -c "SELECT pg_drop_replication_slot('electric_slot_default');" # Or set a safety limit psql -c "ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';" psql -c "SELECT pg_reload_conf();" ``` Replication slots retain WAL indefinitely when Electric is disconnected. Postgres disk fills up. Either drop the slot or set `max_slot_wal_keep_size`. Source: `website/docs/guides/troubleshooting.md:203-316` See also: electric-deployment/SKILL.md — Many sync issues stem from deployment configuration. See also: electric-shapes/SKILL.md — onError semantics and backoff behavior. ## Version Targets @electric-sql/client v1.5.10.