Troubleshooting

Ordered roughly by how often they come up.

The extension says the app is not running#

The two halves gate each other, so this is the extension refusing to half-work rather than a bug.

1. Is the app actually running? On Windows look in the notification area.
2. Press Set Up Everything in the app. It re-registers the bridge, which is the usual casualty of a browser update.
3. If it still fails, the bridge registration is missing. The app's diagnostics dump reports whether the registry entry and the host file both exist.

Perch keeps asking for Screen Recording#

Open System Settings → Privacy & Security → Screen Recording and look for two entries called Perch.app. If there are two, that is the whole answer.

Perch is signed locally rather than by a Team ID, and macOS records that kind of permission per copy of the app, by location — so a Perch you ran from the disk image and a Perch you later dragged to Applications are two different applications as far as the permission database is concerned. Granting one does nothing for the other, and the one you are launching is the one still asking.

To fix it:

1. Quit Perch.
2. Keep exactly one copy, in /Applications. Delete any other — the one still inside the mounted disk image, the one in Downloads, or a build from source.
3. In Screen Recording, select the stale entry and press −.
4. Launch the copy in /Applications and grant it once.

Updating Perch does not cost you the grant: the updater replaces the app in place, at the same path and with the same signature, which is the thing the permission is attached to.

The mirror is frozen#

Check in this order, because the first two are far more common than the third:

• Is the page itself static? Capture is change-driven on Windows: a window showing nothing new produces no new frames. That is not a frozen mirror.
• Is the window minimised? On Windows a minimised window cannot be captured at all. Restore it; it can then be covered as much as you like.
• Is this Chrome without Perch's switches? If the mirror freezes only when the window is fully covered, the browser is throttling the tab. Perch adds the switches that prevent this to the Chrome it launches, so this points at a Chrome it did not launch.

Chrome closed on its own#

The app reports this rather than leaving you with a silently dead mirror, and it tries to say why: the exit code first, then a crash dump if the browser left one in Perch's own profile, then the system's error report.

An exit code of 0 means it was asked to close. 1 usually means a bad command line. The rest are crashes, and the report names the module.

Nothing happens when a site asks to share#

• Confirm you are in the Chrome that Perch launched, not your everyday one. Perch cannot attach to a browser it did not start.
• Confirm the extension is enabled in that browser.
• If the picker appears but the site still sees your real screen, the extension is present but not connected — see the first section.

The installer left files behind (Windows)#

The one thing a running program cannot do is delete the folder it is running from. That step is handed to PowerShell, which waits for Perch to exit first.

If a file was still open, the uninstaller says so and names the folder rather than failing silently. Delete it by hand once nothing is holding it.

Where the logs are#

Windows   %LOCALAPPDATA%\Perch\
macOS     ~/Library/Application Support/Perch/

chrome.log and perch-cdp.log are the useful two: the first is the browser's own output, the second is the conversation between the app and it. Neither contains page content.