Troubleshooting Issues on macOS | Pieces Desktop App

Installation & Updating Fixes

PiecesOS and the Pieces Desktop App can be downloaded using several installation methods, and they can be updated differently depending on the method used.

You can also find information below on how to determine the CPU architecture and OS version of your Apple device.

Alternative Installation Methods

If you're having trouble installing the Pieces Desktop App using the recommended .dmg method, you can try installing using our unified .pkg installers or via Homebrew.

via PKG

Our .pkg files install both PiecesOS and the Pieces Desktop App in a single guided sequence.

If you’re not sure which installer you need based on your device’s CPU, [click here.](/products/desktop/troubleshooting/macos#checking-cpu-type) *macOS 13.0 (Ventura) or higher* *macOS 13.0 (Ventura) or higher* You can also install PiecesOS manually using Homebrew from your device’s terminal.

To do so:

Ensure Homebrew is installed on your system.
Run brew install --cask pieces-os in your terminal to install the Pieces Homebrew package.

Versions & Updates

Many issues can stem from out-of-date MCP integrations, PiecesOS, or the desktop app itself.

Updating the Pieces Desktop App

Update the Pieces Desktop App on macOS by clicking your User Profile in the top left, then hovering over Update and selecting Desktop App or PiecesOS.

To check the Pieces Desktop App for updates on macOS:

Use the **Search** option or locate the Pieces Desktop App within your *Applications* folder Click your `User Profile` in the top left of the main app view Hover over `Update` in the dropdown menu that appears Click on either `Desktop App` or `PiecesOS` from the Update submenu to check for and install updates for that component

You can also click Check for PiecesOS Updates as an alternative to doing so in from the PiecesOS system window in your taskbar.

Common Installation Issues

Common installation issues on Apple devices include having an outdated OS version or choosing the wrong installation package.

Checking OS Version

Pieces applications need at least macOS 13.0 (Ventura). If you're having installation problems, first check that your OS version is up-to-date.

To determine your Apple device’s version of macOS:

Click the `Apple Icon` in the top-left corner of your screen Select `About This Mac` Under your device name (i.e. MacBook Air), look for the last line on the list, titled **macOS**

<Image src="https://storage.googleapis.com/hashnode_product_documentation_assets/meet_pieces_assets/meet_pieces/troubleshooting/macos/macos_checking_about_mac.gif" alt="About This Mac showing macOS version and chip" align="center" fullwidth="true" />

Checking CPU Type

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

To determine what CPU architecture your Apple device utilizes:

Click the `Apple Icon` in the top-left corner of your screen. 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 (i.e., Apple M3)

* **Intel:** You will see an Intel processor (i.e., 2.6 GHz Intel Core i7)

Once you’ve determined your CPU architecture, [download the correct installation package accordingly.](/products/desktop/troubleshooting/macos#alternative-installation-methods)

macOS Permissions

PiecesOS requires specific macOS permissions to function properly. If features like Long-Term Memory or Live Context aren't working as expected, the most common cause is missing system permissions.

Screen & System Audio Recording

PiecesOS needs Screen & System Audio Recording permission to capture on-screen context for features like Long-Term Memory and Live Context.

To enable this permission:

Click the `Apple Icon` in the top-left corner of your screen and select `System Settings` Select `Privacy & Security` from the sidebar Scroll down and click `Screen & System Audio Recording` Find **Pieces OS** in the list and toggle it **on**. If Pieces OS is not listed, click the `+` button at the bottom of the list, then locate and add Pieces OS from your Applications folder.

<Image src="/assets/images/troubleshooting/macos/macos_screen_recording_permission.png" alt="macOS Screen & System Audio Recording settings showing Pieces OS enabled" align="center" fullwidth="true" />

> macOS Screen & System Audio Recording settings with Pieces OS enabled.

macOS may prompt you to quit and reopen Pieces OS for the permission change to take effect.

Microphone

PiecesOS also requires Microphone access to capture audio context for Long-Term Memory.

To enable this permission:

Click the `Apple Icon` in the top-left corner of your screen and select `System Settings` Select `Privacy & Security` from the sidebar Scroll down and click `Microphone` Find **Pieces OS** in the list and toggle it **on**. If Pieces OS is not listed, click the `+` button at the bottom of the list, then locate and add Pieces OS from your Applications folder.

<Image src="/assets/images/troubleshooting/macos/macos_microphone_permission.png" alt="macOS Privacy & Security Microphone settings showing Pieces OS enabled" align="center" fullwidth="true" />

> macOS Microphone settings with Pieces OS enabled.

Restart & Retry

If the installation fails because your macOS version is outdated or you installed the wrong package for your device's architecture, restart your machine and try the installation again from the beginning.

If the problem persists, please open a GitHub issue for further assistance, or book a call with our engineers.