Troubleshoot sync errors

A sync error occurs when the project files on your computer are having trouble reconciling with the project files on the Abstract servers. If you're experiencing sync errors, the data you see on your computer may be different from the data your colleagues can see.

You may see an error message in the sync menu at the top left of your Branches screen which may include:

  • Queued to sync project
  • Syncing failed
  • Queued Generation Assets

Check your connections

Sync errors are sometimes caused by problems with your network or internet connection. Try the following steps to check your connection.

In order to help isolate the cause, it’s best to try each step individually and wait a few minutes for the data to push to the servers before trying the next option.

  • Check for VPNs, proxies, firewalls, or other network tools.
    • Keep only the tools that you would normally use connected and disconnect all others.
  • Try connecting to a different network if one is available.
  • If you're currently connected to a wireless network, try using an ethernet connection.
  • If you have access, reboot your modem and router. (If not, contact your IT department for help.)
  • Log out of Abstract and reboot your machine.

If you've checked your connections and everything is working as expected:

If the sync error will not resolve after checking the scenarios noted above, you can try to resync the project.

Resync your project

Files that appear on the Abstract web app reflect the most up to date changes that have successfully been pushed to Abstract’s servers. The resyncing process will erase all local project data, including uncommitted or pending work on branches. Changes that are only reflected in the desktop app could be deleted. 

If you have uncommitted or pending changes you are unable to push to our servers, please remember to save a backup copy of your work from Sketch to your local machine to avoid any data loss.

Before resyncing the project, confirm that none of the following are causing the errors:

If none of those troubleshooting steps solve your issue, save your files to your local machine and resync your project.

There are five steps to resync your project:

  1. Save the files that don't appear on the web app.
  2. Clear the sync queue and remove project data.
  3. Re-download your project.
  4. Add your saved files back to the project.
  5. Sync your changes to the server.

Save files with changes that don't appear online

Open the Abstract web app and confirm which files show the changes you made and which do not. 

For each file that doesn't appear updated on the Abstract web app::

  1. With the file open in Sketch, click File in the Mac menu bar,
  2. Press and hold the key on your keyboard.
  3. From the File menu, click Save As.
  4. With On Your Mac selected, enter or confirm the filename in Save As and choose a Location you'll remember.
  5. Click Save.

Clear the sync queue and remove project data

Once you've saved the files that do not appear in the Abstract web app, you can clear your sync queue and resync Branches.

Attempting to clear a sync that is in progress will only remove the visual progress indicator. Wait for the sync to fail and then clear the sync queue. Abstract will not attempt any additional sync attempts and you can confirm on the web app which files are the most up to date and need to be saved to your local machine. 

To clear your sync queue and resync Branches:

  1. Open the Branches desktop app.
  2. In the Mac menu bar, click Help.
  3. From the dropdown menu, select Enable Development Menu. The Development menu appears in the Mac menu bar.
  4. Click the Development menu.
  5. From the dropdown menu, select Clear Sync Queue.
  6. On the modal that appears, click Clear to confirm..
  7. In the Branches left navigation pane, find the project you were having trouble syncing.
  8. On the affected project card, click the more options Button-more.png icon.
  9. From the dropdown menu, choose Development.
  10. Click Remove Local Project Data.
  11. Abstract removes the local data from your system.
  12. Your sync queue is now clear.

Re-download your project

After clearing the sync queue, re-download your project. This aligns the project files on your computer with the project files on the web app.

To re-download your project:

  1. Open the Branches desktop app.
  2. In the Branches left navigation pane, click the project for which you want to re-download project files.
  3. Click the [more options] icon.
  4. From the dropdown menu, choose Development.
  5. Click Download project.

Abstract downloads a copy of the project data.

If the download fails, try a different network. If you still have trouble re-downloading your project after changing to a new network, contact Support.

Add your saved files back into your project

After you've cleared out the project files that weren't syncing and you've realigned your project with the Branches web app, you can add your updated files to the project. There are two ways to add your saved files back to your project: replace the old files in a branch (including the main branch), or create a new branch with the files.

To replace the old files with your new files in a branch:

  1. In the Branches desktop app, click the branch where you want to add your saved files.
  2. Click the Files tab.
  3. Right click the file you want to replace with your saved file.
  4. From the dropdown menu, click Replace....
  5. Navigate to the file on your computer that you want to replace this file with.
  6. Click Import.

Abstract overwrites the existing files with the files used to replace them.

To create a new branch with the files:

  1. In the Branches desktop app, find the project you want to add files to.
  2. Click the Branches menu.
  3. Click New Branch....
  4. Enter a Branch name and click Create branch. Abstract pulls the files from the main branch into your new branch.
  5. Click the Files tab.
  6. Right click the file you want to replace with your saved file.
  7. From the dropdown menu, click Replace....
  8. Navigate to the file on your computer that you want to replace this file with.
  9. Click Import.

Abstract adds the files you just saved to your Branches project in a new branch.

Sync your changes to the server

Branches desktop app will attempt to sync any new updates. If the sync doesn't automatically start after 15 minutes, you can try to manually sync your changes.

  1. In the Branches left navigation pane, find the project you were having trouble syncing.
  2. On the affected project card, click the [more options] icon.
  3. From the dropdown menu, choose Development.
  4. Click Force sync project to sync your files to the servers

When your files have been successfully synced, you can go back to your normal process! Feel free to make changes to your files through Branches and commit when you're ready.

If resyncing the project does not resolve the issue, it's possible there's an error in Abstract and you may need to reinstall Abstract.

Reinstall Abstract

If you have tried all the troubleshooting steps above and are still experiencing syncing errors, reinstall the app.

Reinstalling Abstract erases all your local data, including uncommitted or pending work on branches. Verify that you have saved files with changes you don't see online to your computer before you continue.

To reinstall the Abstract desktop app:

  1. Click and drag the Abstract icon to the trash can.
  2. Use Spotlight (⌘+space) and find the following directory: ~/Library/Application Support/
  3. Right click the Abstract folder and choose Move to Trash. Abstract has now been uninstalled.
  4. Download Abstract.
  5. Open Finder and navigate to your Downloads folder.
  6. Find and double click Abstract.
  7. If you receive a security warning, click Open.
  8. A modal appears asking you to move Abstract to your Applications folder. Click Move to Applications.
  9. Open Finder and navigate to your Applications folder. Confirm Abstract appears there.

Abstract is freshly installed on your computer and no project data exists locally yet. Redownload your active projects, as well as any linked libraries. If you had changes not yet successfully synced and had to save files locally, be sure to add your files back into your project and Abstract will attempt to sync your changes.

After your files have been successfully synced, you can go back to your normal process! Feel free to make changes to your files through Branches and commit when you're ready.

If you've reinstalled Abstract and are still having syncing issues, contact Support with your debug logs.

Contact Support with debug logs

If you still have sync errors after reinstalling Abstract, send us debug logs:

  1. Open the Branches desktop app.
  2. In the Mac menu bar, click Help.
  3. From the dropdown menu, select Save debug logs....
  4. Abstract saves the logs in your Downloads folder as a .zip file.
  5. Go to the Contact Support page.
  6. Fill out the form, being sure to mention that you have already attempted to resync and reinstall Abstract.
  7. Drag the logs .zip file from your Downloads folder to the Attachments section of your request.
  8. Click Send to Support and an agent will contact you for further troubleshooting