Fixing a 410 Gone Sync Error

Documentation
1

Fixing a 410 Gone Sync Error

Overview

If task sync fails with an error mentioning 410 or Gone, your
local task database and the WingTask sync server disagree about your
task history. Sync stops working until you fix it.

This error does not clear up on its own. Waiting, or running
task sync again, will not resolve it.

Your tasks are not lost. They are still on your computer, and still in
WingTask. This page explains what the error means, how to tell whether
it applies to you, and how to fix it.

What the Error Means

Your computer and WingTask each keep a copy of your tasks. Alongside
those tasks, Taskwarrior keeps a note of where your copy fits into the
history stored on the server.

A 410 Gone error means the server no longer recognizes that note. From
the server’s point of view, your computer is describing a history it
does not have.

Nothing is corrupted, and no tasks have been lost. It is the record of
where you left off that no longer matches, and Taskwarrior cannot
repair that by itself.

The fix is to rebuild your local task database: save your tasks, clear
the database, let Taskwarrior download a fresh copy of your history
from the server, then put your tasks back.

Does This Apply to You?

This error follows a change to your sync setup. You will usually
recognize at least one of these:

  • You rotated your sync credentials in WingTask.
  • You used Delete my data in WingTask.
  • You changed your Sync URL or Client ID.
  • You copied ~/.taskrc to another device without also copying that
    device’s task database.
  • You set up sync again on a device that had synced before.

The device showing the error may not be the one that changed

This is the part that surprises most people.

The device where you made the change often syncs successfully and
reports no problem at all. It quietly becomes the new starting point
for your history on the server. The error then appears on a different
device, one that was still expecting the old history.

So if you rotated your credentials on your laptop and your desktop now
shows a 410, that is expected. Fix whichever device is showing the
error.

It is not because you haven’t synced in a while

A long gap between syncs does not cause this. WingTask keeps your full
history and does not expire old entries. If you have not run
task sync in months and nothing else about your setup changed, your
next sync will simply catch up.

A related error with the same fix

If your Encryption Secret is wrong, you will see a decryption
failure rather than a 410. The server sends your data, but Taskwarrior
cannot unlock it. The steps below fix that too. Check your credentials
carefully at step 6.

Before You Start

  • Your tasks are preserved. Pending, completed, deleted, and
    waiting tasks all survive this procedure.
  • Your undo history is not. task undo history and the record of
    recent local changes are discarded.
  • You need your current credentials. Find them in WingTask at
    Settings > Taskwarrior Sync. Open that page before you begin.
  • Work on one device at a time. Get one device syncing correctly,
    then move on to the others.

These steps delete your local task database.

Do not skip steps 1 and 2. They create the backup that everything
afterward depends on.

Rebuilding Your Task Database

Run these commands in a terminal, in order.

# 1 — Export your tasks. This is what step 8 puts back.
task export > ~/tasks_backup.json

# 2 — Check the backup BEFORE deleting anything.
grep -c '"uuid"' ~/tasks_backup.json   # tasks in the backup file
task count                             # what Taskwarrior has now

# 3 — Find your task database; its location varies by install.
DATA=$(task _get rc.data.location); echo "$DATA"

# 4 — Save a copy of the database, and of its -wal/-shm files
#     if they exist.
cp "$DATA/taskchampion.sqlite3" "$DATA/taskchampion.sqlite3.bak"
# if exists
cp "$DATA/taskchampion.sqlite3-wal" "$DATA/taskchampion.sqlite3-wal.bak"
# if exists
cp "$DATA/taskchampion.sqlite3-shm" "$DATA/taskchampion.sqlite3-shm.bak"

# 5 — Delete the database, and its -wal/-shm files if they exist.
rm -f "$DATA/taskchampion.sqlite3"
# if exists
rm -f "$DATA/taskchampion.sqlite3-wal"
# if exists
rm -f "$DATA/taskchampion.sqlite3-shm"

# 6 — Confirm your CURRENT WingTask credentials are in place
#     (Settings > Taskwarrior Sync).
task show sync

# 7 — Sync now, before re-importing. This re-establishes sync
#     with your new credentials.
task sync

# 8 — Bring your tasks back.
task import ~/tasks_backup.json

# 9 — Push them up.
task sync

At step 2, the first number is how many tasks are in the backup file.
If it is 0, stop. The export did not work, and there is nothing to
restore from. The second number is what Taskwarrior currently holds, as
a rough comparison.

At step 6, the Sync URL, Client ID, and Encryption Secret
must match what WingTask shows at Settings > Taskwarrior Sync. If they
do not, correct them before continuing.

Why the Order Matters

Step 7 looks unnecessary. You have just deleted the database, so
syncing an empty database seems pointless. It is the step that fixes
the problem.

Taskwarrior only downloads a fresh copy of your task history from the
server when the local database is completely empty. That is the one
moment it is willing to start over.

If you import your tasks before that first sync, the database is no
longer empty, the download never happens, and the same error comes
back.

The order is: delete, sync, then import.

If Something Goes Wrong

You now have two backup files, and they do different jobs.

File What it is for
tasks_backup.json What step 8 restores your tasks from
taskchampion.sqlite3.bak The undo for the whole procedure

The .bak file is the only true undo. Restoring it returns your
database to exactly what it was before you started, including your undo
history.

To stop partway through and go back:

rm -f "$DATA/taskchampion.sqlite3"
mv "$DATA/taskchampion.sqlite3.bak" "$DATA/taskchampion.sqlite3"

This puts you back where you began. Sync will still fail, because
nothing has changed on the server, but you have lost nothing.

Confirming It Worked

A successful task sync only tells you that your computer agreed with
itself. It is not proof that your tasks reached WingTask.

Open WingTask in a browser and check that your tasks are there. Keep
both backup files until you have done this. Once you are satisfied, you
can delete them:

rm ~/tasks_backup.json
rm "$DATA/taskchampion.sqlite3.bak"

Your Other Devices

Once one device is syncing correctly, each remaining device needs only
steps 3 through 7: find the database, back it up, delete it, check the
credentials, and sync. There is no need to export or import, because
the tasks come down from the server.

That applies only if the device has no unsynced changes. If it does, or
if you are unsure, run the full procedure on that device as well so its
changes are captured in step 1 and restored in step 8.

Notes

  • Every device must use the same Client ID and Encryption
    Secret    . Copy them from Settings > Taskwarrior Sync.
  • Your Client ID and Encryption Secret are effectively
    passwords. Do not paste them anywhere public.
  • This procedure keeps all of your tasks. It discards your task undo
    history and the record of recent local changes.
  • Fix one device at a time, and confirm it worked before moving on.

Related Topics

Documentation Index
Deleting Your WingTask Data