electric-debugging

name	electric-debugging
description	Troubleshoot Electric sync issues. Covers fast-loop detection from CDN/proxy cache key misconfiguration, stale cache diagnosis (StaleCacheError), MissingHeadersError from CORS misconfiguration, 409 shape expired handling, SSE proxy buffering (nginx proxy_buffering off, Caddy flush_interval -1), HTTP/1.1 6-connection limit in local dev (Caddy HTTP/2 proxy), WAL growth from replication slots (max_slot_wal_keep_size), Vercel CDN cache issues, and onError/backoff behavior. Load when shapes are not receiving updates, sync is slow, or errors appear in the console.
type	lifecycle
library	electric
library_version	1.5.10
requires	["electric-shapes","electric-proxy-auth"]
sources	["electric-sql/electric:packages/typescript-client/src/client.ts","electric-sql/electric:packages/typescript-client/src/fetch.ts","electric-sql/electric:packages/typescript-client/src/error.ts","electric-sql/electric:website/docs/guides/troubleshooting.md"]

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