What causes "sync hub status: response requires protocol_version 2" in thedotmack/claude-mem?

Check the hub's deployed version and its supported protocol_version.

sync hub status: response requires protocol_version 2

Error message

sync hub status: response requires protocol_version 2

What it means

Thrown when the status object's protocol_version field is not strictly equal to 2. The client speaks sync protocol v2 only, so any other value (missing, 1, 3, or wrong type) is a hard contract failure before any sequence field is read.

Source

Thrown at src/services/sync/CloudSync.ts:610

      const syncMode = response.headers.get('X-Sync-Mode');
      if (syncMode !== null || response.ok) this.emitSyncMode(syncMode);
      if (!response.ok) {
        const body = (await response.text().catch(() => '')).slice(0, 200);
        throw new Error(`sync hub status ${response.status}: ${body}`);
      }

      let parsed: unknown;
      try {
        parsed = await response.json();
      } catch {
        throw new Error('sync hub status: response is not JSON');
      }
      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
        throw new Error('sync hub status: response must be an object');
      }
      const record = parsed as Record<string, unknown>;
      if (record.protocol_version !== 2) {
        throw new Error('sync hub status: response requires protocol_version 2');
      }
      if (
        typeof record.epoch !== 'string'
        || typeof record.head_seq !== 'string'
        || typeof record.projected_seq !== 'string'
      ) {
        throw new Error('sync hub status: response requires decimal-string epoch/head_seq/projected_seq');
      }
      const epoch = assertCanonicalDecimal(record.epoch, { positive: true });
      const headSeq = assertCanonicalDecimal(record.head_seq);
      const projectedSeq = assertCanonicalDecimal(record.projected_seq);
      if (compareCanonicalDecimals(projectedSeq, headSeq) > 0) {
        throw new Error('sync hub status: projected_seq exceeds head_seq');
      }
      this.hubStatus = {
        checkedAt,
        reachable: true,
        epoch,

View on GitHub (pinned to d768ba3643)

Solutions

Check the hub's deployed version and its supported protocol_version.
Upgrade or downgrade the hub so it speaks protocol_version 2.
Upgrade the claude-mem client to the version matching the hub's protocol.
Confirm you are pointed at the correct hub environment for this client version.

Example fix

// before: client v2 against a hub still on protocol v1
// hub /v1/sync/status -> {"protocol_version":1,...}
// after: hub upgraded to v2
// hub /v1/sync/status -> {"protocol_version":2,...}

Defensive patterns

Strategy: validation

Type guard

function isHubProtocolMismatch(e: unknown): boolean {
  return e instanceof Error && /sync hub status: response requires protocol_version 2/i.test(e.message);
}

Try / catch

try { await cloudSync.status(); }
catch (e) { if (isHubProtocolMismatch(e)) { markHubIncompatible(e.message); /* disable sync */ return; } throw e; }

Prevention

Deploy hub and client versions that both speak protocol_version 2.
Run a version-compatibility check at start-up and disable sync gracefully on mismatch.
Coordinate hub rollouts so clients are not pointed at a different-protocol hub.

When it happens

Trigger: The hub is running a different protocol major version — an older hub returning protocol_version 1, a newer hub returning 3, or the field missing/misspelled entirely.

Common situations: Version skew between the claude-mem client and the sync hub (client upgraded, hub not yet, or vice versa); pointing at a hub built for a different protocol generation; hub deployment partially rolled out.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/c6d639da0aa6a7f4. Report an issue: GitHub.