Cross-Platform Issues

Learn the troubleshooting steps to take if the Pieces Desktop App isn't working as expected, no matter your operating system.

Basic Troubleshooting

Find links to detailed sections on specific troubleshooting steps as well as information on choosing between cloud and local models, system requirements, and more.

All your Pieces data, including snippets, tags, embeddings, LTM-2 memory, settings, logs, and Pieces Copilot history, is securely stored in the com.pieces.os and com.pieces.pfd folders on your device.

This gives you full control over backups, sharing, and privacy.

Database & Log Paths

You can find your database and support logs at the path below for your specific platform.

  • macOS—~/Library/com.pieces.os/

  • Windows—C:\Users\<username>\Documents\com.pieces.os\

  • Linux—~/.local/share/com.pieces.os/

Don’t forget to switch username with our actual system username.

Logs, Backups & Cloud Functionality

This dedicated On-Device Storage documentation provides more information about finding your logs, creating manual backups outside of the Pieces Desktop App, and opting in to cloud-only features.

  • Sharing Logs—Zip the latest 2–3 files from …/production/support/logs/ and attach them to your issue or DM.

  • Backup & Reset—Copy com.pieces.os to back up your database—or copy zip it, and rename it something other than production to reset your database.

  • Cloud Functionality—Nothing moves off-device unless you enable Personal Cloud or call a third-party model (e.g. OpenAI).

Versions & Updates

Many issues can stem from having an out-of-date Pieces Desktop App.

Updating Pieces Desktop

The Pieces Desktop App will update automatically.

For standalone & alternative installations, updates are checked daily or when you open the application. You'll be prompted to install or delay the update if one is available.

See your platform-specific update instructions on updating the Pieces for Developers Desktop App:

Connection Issues with Pieces Desktop

You may occasionally encounter connection issues between PiecesOS and Pieces Desktop App, resulting in difficulty finding saved materials, issues generating shareable links, and hanging responses from the Pieces Copilot.

The quickest way to resolve this basic connection issue is to restart PiecesOS and the Pieces Desktop App, then check for updates.

Restarting Pieces Suite & Checking Updates

To restart and check for updates for PiecesOS and Pieces Desktop:

1

Make Sure PiecesOS is Running

Ensure PiecesOS is running (look for the Pieces Icon in your system tray or menu bar)

2

Exit PiecesOS

Click on the PiecesOS icon and press the power off button or the exit button in the top right.

3

Close Pieces for Developers

Make sure the Pieces Desktop App is closed by clicking the x button on the top right or by closing it through task manager.

4

Open Pieces Desktop

After opening Pieces Desktop App, PiecesOS will open automatically

  • If there are updates, you will be prompted to update both PiecesOS and Pieces for Developers.

Common Installation Issues

Common issues can occur when setting up the Pieces Desktop App for the first time.

Platform-specific solutions are detailed on their respective OS pages:

Checking Hardware

It may be necessary to verify your system’s specifications if you experience ongoing issues.

See the OS-specific pages for instructions on how to check CPU, RAM, and GPU details:

Updated on
Troubleshooting
macOS