Possible sync error deleted a style; can't import JSON

[wjandrea]

Description

I was working on a userstyle and when I saved it, I got a popup saying something like the style had changed and asking if I wanted to reload it. I didn't know why it would have changed, so I clicked no and continued working on it. Then that kept happening when I saved it, so I tried clicking yes and when it reloaded, it was gone.
Thankfully I have a copy.

Note: I can't remember now if there was an error or if it was a blank editor. Firefox's history doesn't seem to track extension pages.

When I checked the Stylus dashboard, I noticed that a sync was happening and seemed to be stuck. After a few minutes it said something like the database was currently in use and the lock would expire in an hour. I'm guessing a sync happened in the background while I was working on the style, and there was a hiccup between Stylus and my Dropbox account, and that's why the style got deleted, but it's only a guess. This isn't my field.

Sidenote: I paused syncing on my PC Dropbox in order to make a copy. I do have my userstyles in a Git repo, but I've been lazy about keeping it updated so I've been relying on the sync.

I found the relevant userstyle JSON in my Dropbox, but when I try importing it, nothing happens. The style doesn't get imported but no error appears, not even in the browser console.
I'm guessing the import can't handle this file format and there's no error because this situation was unanticipated.

I tried clearing the lock, and the sync went through, but now the file is just a stub containing {"_rev":1773527561364}. That number is the timestamp in milliseconds UTC (2026-03-14 22:32:41.364), and seems to be either when the style was last edited or when the sync went through.

How do I recover from here when I can't import the JSON?
Or is the import supposed to work?
Can I replace the stub with the copy and then it'll sync properly?

I could parse the JSON with Python, but the CSS is in four sections each with different domains, so it would be arduous to re-enter everything.
I guess I could parse it back to Mozilla format, but I have to imagine there are already tools that can do that.

System Information

• OS: Debian Linux
• Browser: Firefox 148.0
• Stylus Version: 2.3.19

Screenshots, links, CSS

(I don't think I have anything useful to put here.)

[tophf]

To make that json file importable you can add [ at the beginning and ] at the end of it.

@eight04, how do you think such scenario should be handled in general i.e. should we just prioritize editor ignoring the remote file or ask a question about sync specifically to let the user decide?

[eight04]

I tried to recreate the issue, by deleting a WIP style from another browser:

1. Prepare browser A and browser B with a style synced.
2. In browser A, modify the style without saving.
3. In browser B, delete the style.
4. Sync B and A. Complete without error.
5. Get an alert in browser A:
6. Click "Cancel"
7. Save the style without error.
8. Sync A and B. Complete without error.

I think the editor wants to close itself at step 5, but stopped by beforeunload confirmation.

I also tried removing code:

9. Prepare browser A and browser B with a style synced.
10. In browser A, modify the style without saving.
11. In browser B, remove all rules and save.
12. Sync B and A. Complete without error.
13. Get a confirmation in browser A:
14. Click "Yes", get an error, the editor doesn't reload:
15. Reload manually by pressing F5.
16. All rules are removed, but I get a dialog with my previous WIP:

In either case, I can't reproduce. One main difference is that the sync process didn't stuck on my side.

On your side, I guess Stylus pushed an "empty document" similar to this bug:
#1503

Resulting a JSON without the actual data.

---

For @wjandrea

How do I recover from here when I can't import the JSON?

If your JSON looks likes:

{
  doc: {...},
  _rev: ...
}

You can try:

d = json.loads(YOUR_JSON)
# "doc" key stores the actual style object
style_obj = d["doc"] 

# avoid id conflict
del style_obj["id"]
del style_obj["_id"]
del style_obj["_rev"]

# create an array
style_obj_arr = [style_obj]

s = json.dumps(style_obj_arr)

# ... then store to a file and import it to Stylus

Can I replace the stub with the copy and then it'll sync properly?

No. Stylus uses a history file to track changed data. Simply change the stub won't make it sync.

---

For Stylus, we can:

1. Investigate why the sync stuck. An unresolved promise? Other bugs? Or it is just caused by browser termination?
2. Investigate why undefined is pushed.
3. Guard onGet to reject undefined:

   stylus/src/background/sync-manager.js

   Line 184 in 0d6b4f6

   onGet: _id => getByUuid(_id) || uuidIndex.custom[_id],

   const data = getByUUID(...)
   if (!data) {
     // NOTE: we can try deleting the style on the cloud, 
     // BUT if the local db is broken while the sync queue still running
     // we will actually remove valid styles on the cloud.
     // ctrl.delete(id, rev)
     throw new Error(`Invalid style ID: ${id}`);
   }
   return data

4. Probably should fix Reject onGet if it returns undefined? eight04/db-to-cloud#25
5. Fix TypeError at step 14.
6. Display a graceful confirmation at step 5 if there is a WIP.

[eight04]

@eight04, how do you think such scenario should be handled in general i.e. should we just prioritize editor ignoring the remote file or ask a question about sync specifically to let the user decide?

The current design should be fine because the user can revert back to previous WIP after the external reload.

Displaying a diff will be even better, so the user will know what had been changed.

[tophf]

Regarding the stuck sync, I wonder if Stylus should add a button to force-retry? Maybe after several automatic retries have failed.

[eight04]

Now I think this might be an unavoidable race condition. There is no way to prevent the client from queuing an update after the delete.

The problem is what should we do in this situation. In a system that keeps the metadata of deleted documents, the system can fetch the deletion revision and compare it to the update revision, then decide which wins. This is impossible in Stylus.

What Stylus can do is to let the deletion always win, and queue a delete operation to overwrite the update. But this method may accidentally sync a broken DB to the cloud.

Currently we make onGet always throw when document is not found. But then there is no way to resolve this "invalid update operation". If a user goes into this situation, the invalid update will stuck in the queue forever. The only way to get out is to reset the sync by reconnecting.

This is much safer because reconnecting won't purge the cloud. However, this can be annoying if the race condition happens frequently.

Showing the error to users won't help either because it only contains an id and a revision tag.

[wjandrea]

To make that json file importable you can add [ at the beginning and ] at the end of it.

That didn't work. @eight04 seems to be saying there's more to it than that.

[wjandrea]

by deleting a WIP style from another browser

I didn't delete it though. I have no idea why it disappeared. A sync error is my best guess at the cause, but I don't know why that caused the userstyle to be removed (or truncated or stubbed or whatever you'd call it).

[wjandrea]

13. Get a confirmation in browser A:

Yeah, that sounds like the error I got!

[wjandrea]

@eight04 That Python code worked, thanks!

(Previously I commented that it didn't work, but I just made a typo in my code.)