Scratch

Troubleshooting

Quick fixes for the things most likely to go sideways.

The summon hotkey doesn’t work

The hotkey is a system-wide registration, which requires Accessibility permission.

  1. Open System Settings → Privacy & Security → Accessibility.
  2. Make sure Scratch is in the list and toggled on.
  3. Quit and relaunch Scratch.

If a different app already owns the same key combination, Scratch can’t bind it. Pick a different combination in Settings → Shortcuts, or quit the conflicting app and reopen Scratch.

Capture text doesn’t insert anything

Capture text uses Screen Recording.

  1. Open System Settings → Privacy & Security → Screen Recording.
  2. Make sure Scratch is in the list and toggled on.
  3. Quit and relaunch Scratch.

Gatekeeper blocked the app

If macOS shows a “Scratch can’t be opened because Apple cannot check it for malicious software” dialog, the build was likely interrupted mid-download.

  1. Move Scratch.app to the Trash.
  2. Re-download Scratch.dmg from the Scratch product page.
  3. Drag the icon to Applications and try again.

If the warning persists on a fresh download, contact [email protected].

Buffers look wrong, or settings reset themselves

Open Settings → General → Buffers → Reveal in Finder. Your buffer folder contains:

  • The .md buffer files — these are your data; back them up before doing anything else.

Your preferences (settings.json) and current-buffer pointer (state.json) live separately in Scratch’s app data at ~/Library/Application Support/Scratch/ and stay on this Mac even if you’ve moved the buffer folder elsewhere.

To reset every preference without touching buffers, use Settings → General → Reset to defaults.

To start completely fresh, quit Scratch, move ~/Library/Application Support/Scratch/ aside, and relaunch — Scratch creates a clean folder on next launch.

I want to see the logs

Scratch logs to the standard Electron locations on macOS:

~/Library/Logs/Scratch/main.log
~/Library/Logs/Scratch/renderer.log

These rotate at a few MB. Attach the relevant log to any bug report.

How to report an issue

Email [email protected] with:

  • Your Scratch version (visible in Settings → About).
  • Your macOS version.
  • A short description of what you did, what happened, and what you expected.
  • Any relevant log file (see above).

Scratch is built by one person. Reports get read.