Troubleshooting

If the Pieces Desktop App isn't working properly, start here. This page explains our troubleshooting documentation and guides you to the right solution for your issue.


Using the Guides

Click one of the links below to get started troubleshooting on your device—or browse the cross-platform troubleshooting documentation for more general fixes.



Cross-Platform Issues

This cross-platform troubleshooting documentation covers the Pieces Desktop App and PiecesOS, including updates, connectivity, system requirements, best practices for running local LLMs with Ollama, model selection for your hardware, and solutions for crashes due to limited resources or GPU compatibility.

macOS + Windows + Linux
macOS + Windows + Linux

Use the Cross-Platform page if you’re not sure where to begin or if your issue isn’t clearly related to your operating system.

On the Cross-Platform troubleshooting guide, you’ll find:

macOS Issues

This macOS guide helps troubleshoot installation and update issues for PiecesOS and the Pieces Desktop App on macOS, covering manual installs (PKG, DMG, Homebrew), checking macOS version and CPU type, and fixing compatibility or outdated software problems.

Windows Issues

Windows users can find troubleshooting steps for installing, updating, or running PiecesOS and the Pieces Desktop App on Windows. It includes manual installation, update instructions, system checks, and solutions for issues with outdated Windows versions, dependencies, or hardware compatibility.

Linux Issues

Ubuntu 22+ Linux users can use this guide to troubleshoot PiecesOS and the Pieces Desktop App. It covers updating via Snap, checking system compatibility, and fixing common installation or display issues. It also offers tips for adjusting GPU settings and verifying hardware and Ubuntu version compatibility.

Additional Assistance

If you’ve followed the applicable troubleshooting steps and still experience problems, consider visiting our community forums for additional guidance, opening a GitHub issue, or booking a call with our engineers.

You can also find additional support resources here.

Updated on