PiecesOS | Troubleshooting

Read about what actionable troubleshooting steps to take if PiecesOS isn’t working as expected on your macOS, Windows, or Linux device.

Common Installation Issues

Find information on troubleshooting common installation and update issues for PiecesOS.

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).

Checking System Specifications

Navigate between the grouped tabs below to find information on several common installation issues users experience when downloading and installing PiecesOS.

macOS | Checking System Specifications

It is imperative to install the right version of PiecesOS depending on whether your chip is ARM or Intel-powered.

Intel and Apple Silicon (ARM) devices run on entirely separate CPU architectures, so downloading the wrong package for your Apple device can cause apps from the Pieces Suite to be rendered useless.

To determine what CPU architecture your Apple device utilizes:

  1. Click the Apple () icon in the top-left corner of your screen.

  2. Select About This Mac, and look for the Overview section. The first line will contain your CPU type:

  • Apple Silicon / ARM: You will see an M-Series processor, e.g., Apple M3

  • Intel: You will see an Intel processor, e.g., 2.6 GHz Intel Core i7

Once you’ve determined your CPU architecture, download the correct PiecesOS file accordingly.

Versions & Updates

Many issues can stem from out-of-date plugins, extensions, or PiecesOS itself.

macOS | Updating PiecesOS

To restart and check for updates to PiecesOS on macOS:

  1. Restart PiecesOS

  2. Ensure PiecesOS is running (look for the Pieces Icon in your system tray)

  3. Check for and install available updates

Checking OS Version

Having an out-of-date operating system version can cause a range of installation issues with PiecesOS, including scenarios in which the entire application refuses to run.

macOS | Checking OS Version

Pieces Suite applications require a minimum macOS version of macOS Ventura. If you’re experiencing installation issues, you should check your OS version to ensure it’s up-to-date.

To determine your Apple device’s version of macOS:

  1. Click the Apple icon in the top-left corner of your screen

  2. Select About This Mac

  3. Under your device name (i.e., MacBook Air), look for the last line on the list, titled macOS

The macOS line will report what version of macOS installed, e.g., Sequoia 15.1.1.

Issues Launching PiecesOS (Windows)

Some users who have enabled Controlled Folder Access (CFA) as a security measure may receive a notification that Pieces is attempting to bypass this security wall.

To work around this issue, you must add the executable path for PiecesOS to your allowlist.

PiecesOS fails to launch when CFA is enabled because the executable path for the application writes data to the Documents folder.

CFA disables and blocks any request to modify files (in this case, writing & saving data), so PiecesOS cannot launch itself.

Keep in mind that this path references the specific PiecesOS version and will change over time as you continue to update the software.

You can also disable CFA as a security measure if you do not require it as part of an enterprise scenario or for any other reason.

To decide which apps PiecesOS has access to, you can easily enable and disable specific sources from the Long-Term Memory Access Control panel.

Accessing Pieces Logs (Windows)

On Windows machines, Pieces writes its log files under your local AppData folder. You’ll find two separate folders depending on which component you’re using:

  • Pieces OS (POS) logs:
    C:\Users\<USERNAME>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Support
  • Pieces Desktop (PFD) logs:
    C:\Users\<USERNAME>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.pfd\production\Support

Replace <USERNAME> with your Windows account name

Contact Support

If you’ve ensured your device meets the recommended and minimum specifications, you’ve performed a clean installation, updated your OS, and checked PiecesOS for updates, and you’re still experiencing issues, visit our support page for more resources.

Updated on
Quick Menu
Ollama