Pitfalls

Common mistakes that cause data corruption, sync issues, or unexpected behavior—and how to avoid them.

Overview

CRDT-based applications can fail in subtle ways that are hard to debug. Many issues only appear when multiple users edit simultaneously, making them difficult to reproduce in development. This section documents the most common pitfalls organized by what you’re doing when you encounter them.

Topics

• Data Modeling - Schema and structure decisions that cause problems
• API Usage - Mistakes when calling Yjs methods
• Events & Sync - Handling the distributed nature of CRDTs

The Cost of CRDT Bugs

CRDT bugs are particularly problematic because:

1. Data corruption spreads - Once corrupted data syncs to other clients, it’s everywhere
2. Hard to reproduce - Issues may only occur with specific timing of concurrent edits
3. Silent failures - Changes may be lost without any error messages
4. Difficult to fix - Corrupted documents may need manual repair or data loss

Quick Reference

Quick Checklist

Before deploying a collaborative feature, verify:

• Complex content in Y.Map with IDs, order in Y.Array
• All references use IDs, not indices
• Never mutating objects after set()
• Using yDoc.getMap() not new Y.Map()
• Changes batched in transactions
• Undo uses trackedOrigins to isolate users
• Observers check transaction.local when needed
• Awareness updates are debounced
• Large binary data uses blob storage, not CRDT

Most Common Issues