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.

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.