General Troubleshooting

If you have uncommitted or pending changes you are unable to push to our servers but you’d like to keep, use "Save as..." from the Sketch file to save a copy to your desktop to prevent any data loss.

Restart Abstract

If you run into unexpected behavior in Abstract, you can first try to refresh the app or quit and restart your machine.

To refresh the desktop app:

Use Command + R or Click View > Reload

To complete a full restart:

  1. Press and hold Command + Q to quit Abstract.
  2. Restart your machine.

Error while opening a file or when trying to commit a file

Error messages:

  • plugin error: app not installed
  • Could not load Abstract :(
  • Failed to open

If you encounter any of the above error messages when opening or committing a file, make sure all applications are properly installed.

To confirm that all applications are properly installed:

  • Ensure that Abstract and Sketch or Adobe XD are located in the Applications folder.
  • If there is more than one instance of the application, delete all but the most recent version.
  • Confirm that all applications have the correct name (for example, not Abstract 2).

If all applications are properly installed, you may need to reinstall the plugin.

Reinstall the plugin

To reinstall Sketch plugin:

  1. In Sketch, go to Plugins › Manage Plugins
  2. Right click Abstract to uninstall.
  3. Select Move to Trash.
  4. Restart both Abstract and Sketch.
  5. Attempt to open a file from Abstract. The plugin reinstalls automatically.

To reinstall Adobe XD plugin:

  1. In Adobe XD, go to Plugins › Manage Plugins...
  2. Select the '...' next to Abstract, then click Uninstall.
  3. Restart Abstract and Adobe XD.
  4. Attempt to open a file from Abstract. The plugin reinstalls automatically.

Locate a backup file

Backup files are automatically created when you commit changes and reopen a file in Abstract or when a branch is renamed.

You can find a copy of your work by locating the backup file.

To locate a backup file in Sketch:

  1. In the Abstract desktop app, navigate to the branch you were working in.
  2. Select the Files tab and click Edit in Sketch to open the file.
  3. In Sketch, press and hold Command and click on the filename in the Sketch titlebar.
  4. Select the top folder from the menu with the backup file.
  5. Use File > Duplicate to save a copy of the file to Desktop.
  6. Update the file extension on the Desktop version of the file from .abstractBackup.sketch to .sketch.
  7. Locate the out-of-date file in Abstract.
  8. Right-click on the file name to select Replace from the menu.

Locate file size

We recommend keeping files below 250MB in size for the best performance. If you're working with files larger than that, or especially complex files with hundreds of layers or dozens of pages, consider reorganizing your work into smaller files.

To find out what size your file is:

  1. Locate the file in Abstract that you want to view.
  2. Open the file from Abstract by clicking Open in Sketch.
  3. Hold the command key to CMD+click the file name in the Sketch title bar.
  4. A file menu opens. Click the arrow next to the folder closest to the file name.
  5. A Finder window opens. Select the file to view its size in the Finder preview area or right-click to Get Info.

Index is locked

Error message:

the index is locked; this might be due to a concurrent or crashed process

To remove index.lock:

  1. In the Abstract desktop app, click Help > Enable Development Menu.
  2. Right click on the broken project and select Development > Open in Terminal.
  3. Paste rm .git/index.lock into the Terminal and press enter.
  4. Click Help > Disable Development Menu.

Reinstall the Abstract macOS app

If you have uncommitted or pending changes you are unable to push to our servers but you’d like to keep, use "Save as..." from the Sketch file to save a copy to your desktop. The reinstall process erases all local data, including uncommitted or pending work on branches.

To reinstall the Abstract desktop application:

  1. Read the warning above to avoid losing data.
  2. Uninstall Abstract moving the application to the trash can.
  3. Use Spotlight to find this directory on your computer: ~/Library/Application Support/
  4. Delete the Abstract folder.
  5. Download and install Abstract Branches.
  6. Confirm Abstract has been added to the applications folder.