Setup & Update Help

Resolve launch, compatibility, and update issues with an existing Pieces setup.

Quick fixes

Pieces will not launch after a Windows update

This can happen when Windows does not restart the app package or background service cleanly.

Restart Windows, then open PiecesOS before opening Pieces Desktop.
Open Settings → Apps → Installed apps → Pieces Desktop → Advanced options and choose Repair.
On a managed computer, ask your IT administrator to confirm that Pieces and its background service are allowed to run.

Pieces is blocked or will not launch on macOS

macOS may block an existing app after a system update or security-policy change.

Check your chip: click Apple menu → About This Mac and look for Apple Silicon (M-series) or Intel.
Open System Settings → Privacy & Security and review any message about Pieces.
Quit both Pieces Desktop and PiecesOS, then reopen PiecesOS before reopening the desktop app.

Pieces will not launch on Linux

Display-server permissions or a background process can prevent an existing installation from opening correctly.

Quit any running Pieces Desktop and PiecesOS processes.
Confirm whether your session uses X11 or Wayland and review the matching display permissions.
Reopen PiecesOS first, then open Pieces Desktop and collect logs if the issue continues.

Use the platform troubleshooting guide that matches your computer.

Include your operating system, version, CPU architecture, and the behavior you are seeing.