Understanding the _sync:sequence and why it is 0


I am relatively new to Couchbase, Couchbase Mobile and the sync gateway, and I am interested in understanding how the interplay between a bucket and its shadow bucket for the sync gateway.

We have seen some issues where some documents stop replicating to the shadow bucket. As I looked into the documents in the shadow bucket I can see that

{ _sync: {
  "sequence": 0
  "recent_sequences": [

for the documents that are not being updated in the shadow bucket, when they are updated in the “original” (what is the terminology? Bright?) bucket. What does this mean? When is the sequence set to 0? Does is indicate conflict, or any other errors?

When I remove the 0 from the list of recent_sequences and set sequence to the last entry of recent_sequences the document is replicated to the shadow bucket, and subsequently devices, and all looks good. Is it safe to do this edit manually?

I hope that this is the right forum, and that you can help me understand - or point me in the right direction to understand :slight_smile:

Best regards,

You shouldn’t edit the _sync data manually - it has the potential to corrupt your replication.

As far as I know, there shouldn’t be a case where a document gets its sequence set to zero - either as the main sequence value, or as an entry in recent_sequences. This sounds like a bug, and I’d request that you file an issue here with some more details on what the update flow is for the problematic document (i.e. what updates are being made in the source bucket, etc). https://github.com/couchbase/sync_gateway/issues

More generally, bucket shadowing isn’t the recommended configuration for Sync Gateway. What aspects of your use case led to the decision to use bucket shadowing?

Thank you for your answer. My belief was also that I shouldn’t be editing the meta data, but it let me to some insights :slight_smile:

I will open an issue, describing our setup and situation as best as I can - unfortunately I can’t reproduce this behaviour.

We have 3 parts of our system:

  • The web application
  • A number of services
  • A smartphone application (Android and iOS) that needs to work offline - we are running couchbase lite on the devices.

Most documents are only touched from one place, typically a service, but some documents can be created or edited by our users either through the web application, or from the smartphone application.

I am relatively new to the team and the setup, but as I understand it bucket shadowing is needed for this to work as needed.

Future readers: see this issue on Github

Basically it seems like our Couchbase Server was overloaded, which combined with a bug in the sync gateway sequence incrementer, caused this behaviour.