PiecesOS Help & Learning

Fix launch and connection issues, manage on-device storage, and find the logs support needs.

Work through launch, connection, and platform-specific fixes.

Collect recent logs before opening a bug report.

Locate local databases, backups, and storage folders.

Quick fixes

PiecesOS won't start or keeps crashing

PiecesOS may fail to launch if it was installed to a cloud-synced folder, the OS is outdated, or Windows Controlled Folder Access is blocking writes.

Confirm your OS meets minimum requirements: macOS 12+, Windows 10 1809+, or Ubuntu 22+.
If installed to OneDrive, iCloud Drive, or another synced location, uninstall and reinstall to the default path.
On Windows, add PiecesOS to the Controlled Folder Access allowlist if CFA is enabled.
Restart your computer and reopen Pieces Desktop.

PiecesOS update failed or stuck

Updates can fail if the previous version is still running or if the installer file is blocked.

Quit Pieces Desktop and PiecesOS completely (use Task Manager or Activity Monitor if needed).
Open Pieces Desktop again. It will relaunch PiecesOS and prompt for the update.
On Windows with .appinstaller, quit both apps before retrying the update.
If updates continue to fail, collect your logs and contact support with the app version and operating system.

Where are my logs and local data?

PiecesOS stores logs and databases locally. Attach recent logs when reporting a bug.

macOS: ~/Library/com.pieces.os/production/Support/logs/
Windows: %LOCALAPPDATA%\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Support\
Linux: ~/.local/share/com.pieces.os/logs/

Zip the latest two or three log files and attach them to your GitHub issue or support request.

Open the canonical Pieces documentation for each dependency or task.

Try the troubleshooting guide first, then include recent logs in your report.