electric-debugging

このスキルは、electric-shapes と electric-proxy-auth を基盤としています。先にそちらを読んでください。

Electric — 同期の問題のデバッグ

セットアップ

デバッグログを有効にして、再試行やステートマシンの動作を確認します。

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
  },
})

主なパターン

エラーの再試行動作

エラー	自動再試行？	対応
5xx サーバーエラー	はい（指数バックオフ）	待機して再試行
429 レート制限	はい（Retry-After を尊重）	待機して再試行
ネットワークエラー	はい（指数バックオフ）	待機して再試行
4xx（429 以外）	いいえ	onError を呼び出します — 手動で再試行するには {} を返します
409 shape expired	はい（自動リセット）	クライアントがリセットして再取得します
MissingHeadersError	いいえ	CORS／プロキシを修正してください — onError が {} を返しても再試行できません

MissingHeadersError の診断

このエラーは、Electric のレスポンスヘッダー（electric-offset、electric-handle）が、通常は CORS によって削除されていることを意味します。

MissingHeadersError: This is often due to a proxy not setting CORS correctly
so that all Electric headers can be read by the client.

修正方法：プロキシの CORS 設定で Electric のヘッダーを公開します。

headers.set(
  'Access-Control-Expose-Headers',
  'electric-offset, electric-handle, electric-schema, electric-cursor'
)

高速ループ検出の診断

コンソールメッセージ：「Detected possible fast loop」と診断情報が表示されます。

原因：プロキシ／CDN のキャッシュキーに handle と offset のクエリパラメーターが含まれていないため、クライアントが同じ古いレスポンスを繰り返し受け取っています。

修正方法：プロキシ／CDN のキャッシュキーにすべてのクエリパラメーターが含まれるようにします。

Vercel の場合は、vercel.json に追加します。

{
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "CDN-Cache-Control", "value": "no-store" },
        { "key": "Vercel-CDN-Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

よくある間違い

重大：プロキシまたは CDN のキャッシュキーにクエリパラメーターが含まれていない

誤り：

# nginx caching without query params in key
proxy_cache_key $scheme$host$uri;

正しい例：

# Include query params (handle, offset) in cache key
proxy_cache_key $scheme$host$request_uri;

同じ offset で 500ms 以内に 5 件のリクエストがあると、高速ループ検出が作動します。クライアントはキャッシュを一度自動消去してからバックオフを適用し、検出が 5 回連続するとエラーをスローします。

ソース：packages/typescript-client/src/client.ts:929-1002

重大：プロキシによる SSE レスポンスのバッファリング

誤り：

location /v1/shape {
  proxy_pass http://electric:3000;
  # Default: proxy_buffering on — SSE responses delayed
}

正しい例：

location /v1/shape {
  proxy_pass http://electric:3000;
  proxy_buffering off;
}

Caddy の場合：

reverse_proxy localhost:3000 {
  flush_interval -1
}

Nginx と Caddy はデフォルトでレスポンスをバッファリングするため、SSE のライブ更新に大幅な遅延が発生します。Electric のエンドポイントではバッファリングを無効にしてください。キャッシュ全体を無効にしないでください。Electric はリクエストの集約にキャッシュヘッダーを使用します。

ソース：website/docs/guides/troubleshooting.md:69-109

中程度：HTTP/2 を使わずにローカル開発で 6 個以上の shape を実行する

誤り：

# Running Electric directly on localhost:3000
# With 7+ shapes, browser HTTP/1.1 queues all requests (6 connection limit)

正しい例：

# 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

ブラウザーの HTTP/1.1 では、オリジンごとに TCP 接続が 6 件に制限されます。shape が多いと、リクエストが互いに待ち行列を作ります。ローカルの HTTP/2 プロキシとして Caddy を使用してください。

ソース：website/docs/guides/troubleshooting.md:28-53

重大：Electric の停止後もレプリケーションスロットをアクティブなままにする

誤り：

docker stop electric
# Replication slot retains WAL indefinitely — disk fills up

正しい例：

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();"

Electric が切断されても、レプリケーションスロットは WAL を無期限に保持します。Postgres のディスクがいっぱいになります。スロットを削除するか、max_slot_wal_keep_size を設定してください。

ソース：website/docs/guides/troubleshooting.md:203-316

こちらも参照：electric-deployment/SKILL.md — 同期の問題の多くは、デプロイ設定に起因します。 こちらも参照：electric-shapes/SKILL.md — onError のセマンティクスとバックオフの動作。

バージョン

対象：@electric-sql/client v1.5.10。