---
title: "Troubleshooting"
description: "macOS sometimes keeps a stale answer for a running app."
url: https://www.bigshot.pics/docs/troubleshooting
---
# Troubleshooting

## Captures fail although Screen Recording is on

macOS sometimes keeps a stale answer for a running app.

1. Quit Bigshot and open it again. The Setup Guide's permission page offers
   **Quit & Reopen** for this.
2. If it still fails, open System Settings › Privacy & Security › Screen
   Recording, remove Bigshot with **−**, add it again, and reopen Bigshot.

A build signed with a different certificate counts as a different app, so
updating from an older unsigned build asks for the permission again.

## A shortcut does nothing

Another app may be taking it. Open Settings › Shortcuts, press **Start
listening**, and press the shortcut. If it does not check off, rebind it.
`⌃⌥` shortcuts also clash with VoiceOver.

## ⇧⌘3 or ⇧⌘4 still opens the macOS screenshot tool

Turn the system shortcuts off in System Settings › Keyboard › Keyboard
Shortcuts › Screenshots. Bigshot cannot take them while macOS has them.

## Window capture took the wrong window

Window takes the frontmost window of another app. Click the window you want
first, then press **⌃⌥W**. Bigshot's own windows are never captured this
way; use Area for those.

## The island is in my screenshot

Captures started by a shortcut or the menu bar leave the island where it is.
Let it collapse to the notch first, or start the capture from the island.

## Captures go to the Desktop instead of my Project

- Check the Active Project in the menu bar or the island's Project pill.
- Projects need a Licence. Without one, every capture goes to the Desktop.

## An agent cannot see my screenshots

- The Project's **Sharing** must be Automatic or Review first. Off empties
  the index.
- In Review first mode, approve each capture with **Share now**.
- Check `.screenshots/index.json` exists in the workspace, and that
  `CLAUDE.md` or `AGENTS.md` has the Bigshot block. Edit the Project and
  re-run the plan to add it.
- A capture marked *Sharing failed* can be retried from **Screenshot
  Context…** or **Retry context** in Settings › Projects.

## Hooks do not run

- Check the menu bar: **Resume Hooks** means they are paused.
- Check the Hook is enabled and its connection shows *Connected*, or has a
  saved key.
- If the Project has ever had sharing on, only tagged, shared captures run
  Hooks. Tag the capture and use **Share now**.
- Open **View Hook Runs…** on the capture for the error and the log.

## A capture disappeared

Look in the Trash. Automatic cleanup moves captures there once they pass the
**Keep screenshots** window. Turn on **Keep** for any capture that should
stay.

## macOS refuses to open an older build

Builds before notarization were stopped with *"Apple could not verify
Bigshot is free of malware"*. Click **Done**, not **Move to Bin**, then run:

```sh
xattr -dr com.apple.quarantine ~/Downloads/Bigshot-*.dmg
```

Or click **Open Anyway** at the bottom of System Settings › Privacy &
Security. Current releases are notarized and open normally.

## The old icon still shows after an update

Delete `/Applications/Bigshot.app` before copying the new version in. macOS
caches icons by path.