thedotmack/claude-mem · error

sync hub push: checkpoint order requires head_seq <= project

Error message

sync hub push: checkpoint order requires head_seq <= projected_seq

What it means

Thrown when the hub returns head_seq greater than projected_seq, violating the checkpoint ordering invariant. head_seq is the durable replicated head; projected_seq is the projected/optimistic sequence. The contract requires head_seq <= projected_seq, so head beyond projected is an inconsistent hub checkpoint.

Source

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

      }
      seqTuple.set(ack.seq, key);
    }

    for (const [key, expected] of sentCounts) {
      const actual = ackCounts.get(key) ?? 0;
      if (actual !== expected) {
        throw new Error(
          `sync hub push: 200 response acknowledgment multiplicity mismatch (expected ${expected}, received ${actual})`
        );
      }
    }
    if (ackCounts.size !== sentCounts.size) {
      // Defensive: the unknown-tuple branch above should make this impossible.
      throw new Error('sync hub push: 200 response acknowledgment multiset mismatch');
    }

    if (compareCanonicalDecimals(response.head_seq, response.projected_seq) > 0) {
      throw new Error('sync hub push: checkpoint order requires head_seq <= projected_seq');
    }
    for (const ack of response.acked) {
      if (compareCanonicalDecimals(ack.seq, response.head_seq) > 0) {
        throw new Error('sync hub push: acknowledgment seq exceeds head_seq');
      }
      if (compareCanonicalDecimals(ack.seq, response.projected_seq) > 0) {
        throw new Error('sync hub push: sent operation is not covered by projected_seq');
      }
    }
  }

  /**
   * Stamp rows / delete outbox entries for a fully validated acknowledgment
   * multiset. The hub may return entries in any order.
   */
  private stampAcked(acked: AckedOp[], pushed: WireOp[]): void {
    const now = Date.now();
    const bodies = new Map(pushed.map(op => {

View on GitHub (pinned to d768ba3643)

Solutions

1. Inspect the hub's head_seq and projected_seq values for the device/user; head must never exceed projected.
2. Fix the hub checkpoint advancement so projected_seq is always >= head_seq at response time.
3. Retry the push after the hub corrects the pointers; do not advance the local cursor on a violating checkpoint.
4. Check hub logs for a projected_seq update that failed after head_seq moved.

try { await cloudSync.push(pushed); }
catch (e) {
  if (e instanceof Error && e.message.includes('checkpoint order requires head_seq <= projected_seq')) {
    logger.error('SYNC', e.message); // hub checkpoint inconsistency
    await scheduleRetry(); return;
  }
  throw e;
}

When it happens

Trigger: validatePushResponse runs compareCanonicalDecimals(response.head_seq, response.projected_seq); a positive result (head_seq > projected_seq) throws. Both values were already validated as canonical decimal strings upstream.

Common situations: Hub bug where the projected pointer lags the durable head (e.g. projected_seq not advanced after a commit), a hub rolling back projected but not head, or version skew redefining what head/projected mean. The client refuses a checkpoint that cannot be linearized.

Related errors

• sync hub push: acknowledgment seq exceeds head_seq
• sync hub push: sent operation is not covered by projected_se
• sync hub push: acked[${index}] must be an object
• sync hub push: malformed acked[${index}]
• sync hub push: 200 response contains an extra or mismatched

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