---

Troubleshooting

If PiecesOS or the Pieces Desktop App isn’t working as expected, start here. This page helps you understand the structure of our troubleshooting documentation and directs you to the appropriate guide for your situation.

---

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

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:

• tips on handling local LLM crashes due to hardware-related issues

• guidance on working with Vulkan-based GPUs

• links to related documentation on checking hardware specifications on your OS

macOS Issues

Troubleshooting steps and details for macOS systems—including topics, such as:

• how to verify your macOS software version

• determining and choosing the correct installation package for different chipsets

• updating PiecesOS and the Pieces Desktop App

Windows Issues

Troubleshooting steps and details for Windows systems—including topics, such as:

• checking for Windows installation updates

• verifying the App Installer is up-to-date

• alternative installation methods for non-Suite installs

• viewing hardware specifications using dxdiag

Linux Issues

Troubleshooting steps and details for Linux systems—including topics, such as:

• confirming compatibility with your Linux distribution

• using snap commands to update PiecesOS and the Pieces Desktop App

• adjusting graphics settings if you encounter UI issues

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.