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:
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:
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 :
{ "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 caching without query params in key
proxy_cache_key $scheme$host$uri;
Correct:
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:
location /v1/shape { proxy_pass http://electric:3000;
Default: proxy_buffering on — SSE responses delayed
}
Correct:
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:
Running Electric directly on localhost:3000
With 7+ shapes, browser HTTP/1.1 queues all requests (6 connection limit)
Correct:
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:
docker stop electric
Replication slot retains WAL indefinitely — disk fills up
Correct:
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.