thedotmack/claude-mem · warning

Observation watermark bump skipped — partial write

Error message

Observation watermark bump skipped — partial write

What it means

syncObservation advances the observations watermark in ChromaSyncState only when addDocuments reports written === requested. A partial write (per-batch failures are tolerated inside addDocuments) skips the bump and logs this warning, so the next boot's backfill retries the observation instead of silently skipping it (CodeRabbit review on PR #2282).

Source

Thrown at src/services/sync/ChromaSync.ts:476

    const documents = this.formatObservationDocs(stored);

    logger.info('CHROMA_SYNC', 'Syncing observation', {
      observationId,
      documentCount: documents.length,
      project
    });

    // Only advance the watermark on a confirmed full write. addDocuments() now
    // returns a written count and tolerates per-batch failures, so a transient
    // Chroma error must NOT mark this observation as synced — otherwise the
    // backfill pass on next boot will skip past it (CodeRabbit review on PR
    // #2282).
    const written = await this.addDocuments(documents);
    if (written === documents.length) {
      ChromaSyncState.bump(project, 'observations', observationId);
    } else {
      logger.warn('CHROMA_SYNC', 'Observation watermark bump skipped — partial write', {
        observationId,
        project,
        requested: documents.length,
        written
      });
    }
  }

  async syncSummary(
    summaryId: number,
    memorySessionId: string,
    project: string,
    summary: ParsedSummary,
    promptNumber: number,
    createdAtEpoch: number,
    platformSource?: string
  ): Promise<void> {
    const stored: StoredSummary = {

View on GitHub (pinned to e2d1df569a)

Solutions

1. Wait for the automatic backfill on next boot — the data is not lost.
2. Check Chroma connectivity/health and fix the transient cause.
3. Confirm later that observation counts converge; do not hand-edit the watermark.

async function chromaHealthy(baseUrl: string): Promise<boolean> {
  try {
    const res = await fetch(`${baseUrl}/api/v2/heartbeat`, { signal: AbortSignal.timeout(2000) });
    return res.ok;
  } catch {
    return false;
  }
}

When it happens

Trigger: Chroma accepts some batches but fails others (transient error, timeout) during an observation sync, returning written < documents.length.

Common situations: Chroma briefly overloaded or restarting, embedder rate limits, or a network hiccup mid-write.

Related errors

• Summary watermark bump skipped — partial write
• Prompt watermark bump skipped — write failed
• Backfill failed: ${error instanceof Error ? error.message :
• Chroma unavailable before write; leaving documents unsynced
• failed to kill prior chroma-mcp tree (best-effort)

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/8d4be38885abff69. Report an issue: GitHub.