Troubleshooting
Most issues come from permissions, missing files, browser sign-in state, or a source that is not actually in the folder.
Perch is an early-access product, so a handful of rough edges are expected, and almost all of them trace back to the same few causes. Before assuming something is broken, it is worth checking the usual suspects: a folder Perch was never granted access to, a file that is not actually where you think it is, a browser session that has signed itself out, or a source you are asking Perch to verify that is not in the workspace. The fixes below are ordered by how often they are the real problem.
When something feels off
Most issues come from permissions, missing files, browser sign-in state, or a source that is not actually in the folder.
Download blocked
Early builds may trigger operating-system warnings. Open the file from the official Perch download link and follow the platform prompt.
Mac says the app is damaged
Perch versions before 2.5.0 were not signed, so macOS can say they are damaged. Download the current version from the Desktop page: it is signed and notarized, so it opens normally. To keep using an older copy, drag Perch Terminal to Applications, run this command in the Terminal app, then open Perch again.
xattr -dr com.apple.quarantine "/Applications/Perch Terminal.app"Folder looks empty
Confirm the desktop app has file access and that the selected folder contains the files you expect Perch to read.
Linux AppImage will not start
AppImages need FUSE 2: install libfuse2 (libfuse2t64 on Ubuntu 24.04 and later). On Ubuntu 24.04 and later, use the .deb instead.
Browser tool is signed out
In the desktop app, open the Browser panel, sign into the target app, then ask Perch to continue from there. The CLI's browser runs in a temporary profile that is never signed in, so do signed-in work in the desktop app.
Citation cannot be verified
Add the missing source to the folder or ask Perch to remove the unsupported claim.
The app feels stale
Quit and reopen Perch. From version 2.5.0 on, the desktop app downloads updates in the background and shows Restart to update when one is ready. To check by hand, choose Check for Updates… from the Perch Terminal menu on a Mac, or from Help on Windows and Linux. On an older version, download the current build from the Desktop page once and install it over the old one. See Desktop app.
The Mac app does not update itself
Perch cannot replace itself while it runs from the downloaded disk image. Drag Perch Terminal to your Applications folder, or choose Move to Applications when Perch offers it, and open it from there.
The CLI says it needs a newer Node
The CLI needs Node 22 or newer and says so when it starts on an older one. Update Node, then run perch again.
The CLI is out of date
Run perch update. If you installed the CLI with a tool other than npm, update it with that tool.
I cannot sign in to my account
If you asked for your account to be deleted, it is locked on every device until it is erased. See Your account.
Still stuck? Email hello@perchai.app.