Shattle on macOS: Why It Couldn’t Access Documents (and the Simple Fix)

## Shattle (app) on macOS: When a Productivity Tool Refuses to See Your Files I installed **Shattle (app)** on a 13-inch MacBook Pro (M2, macOS Sonoma 14.3.1) inside my usual OrchardKit test setup. From the slug and category, it’s clearly an office/productivity utility — something that works with documents, probably syncing or organizing content across folders. My goal was simple: point it to a project directory in Documents and let it index a few hundred files. Nothing exotic. Just a sanity check before rolling it into a wider workflow. Instead, I got a polite but infuriating message inside the interface: “Unable to access selected folder.” No crash. No macOS dialog. Just… refusal. ### First instinct: user error I assumed I had misclicked something. Removed the folder. Added it again. Same error. Then I tried granting Full Disk Access preemptively. System Settings → Privacy & Security → Full Disk Access → toggle it on for the tool. Still couldn’t read anything inside `~/Documents/Projects`. That’s when it clicked. Since macOS Catalina, Documents, Desktop, and Downloads are protected locations. Apps need explicit permission to access them — and that permission is handled by TCC (Transparency, Consent, and Control). Apple explains the privacy model here: [https://support.apple.com/en-us/HT210638](https://support.apple.com/en-us/HT210638) The strange part was that macOS never prompted me for access in the first place. ### False Lead: Blame the Build My second guess was that the binary wasn’t properly signed or notarized, and macOS was silently restricting it. Sonoma has tightened enforcement. So I checked its Gatekeeper status: ``` spctl --assess --verbose /Applications/Shattle.app ``` It passed assessment. I also verified quarantine status: ``` xattr -l /Applications/Shattle.app ``` There was a `com.apple.quarantine` attribute, which is normal for downloaded apps. I removed it anyway, just to eliminate variables: ``` xattr -dr com.apple.quarantine /Applications/Shattle.app ``` Relaunched. No change. At that point I skimmed Apple’s documentation on Gatekeeper behavior to confirm I wasn’t missing something obvious: [https://support.apple.com/en-us/HT202491](https://support.apple.com/en-us/HT202491) But the issue wasn’t launch permission. The app opened fine. It just couldn’t touch the folder I selected. ### The Real Culprit: Folder Picker vs. Drag-and-Drop Here’s the nuance I initially missed. The first time I added the project directory, I dragged it into the app’s window. That feels intuitive, but it doesn’t always trigger the proper security-scoped bookmark flow on macOS. If the app doesn’t request access via the standard file picker dialog, the OS may not grant persistent permission. So I removed the folder again. This time I used the built-in “Add Folder” button inside the interface, which opened the native macOS file chooser. I navigated to Documents → Projects → selected the directory. Immediately, macOS displayed a permission prompt asking to allow access to files in Documents. Allowed. The indexing started instantly. No errors. It turns out the utility wasn’t broken at all. My method of giving it a path bypassed the permission handshake. I found this page helpful while confirming how macOS systems treat file access differently depending on how an app requests it — especially for productivity software: [https://planetgpa.com/office-and-productivity/42883-shattle.html](https://planetgpa.com/office-and-productivity/42883-shattle.html) It aligned perfectly with what I observed: drag-and-drop doesn’t always equal granted access. ### Why This Happens Modern macOS relies heavily on security-scoped bookmarks. When an app uses the official NSOpenPanel (the file picker dialog), the OS attaches a token that allows persistent access to that folder. If the developer doesn’t implement drag-and-drop handling with proper security scope support, the system treats the path as untrusted. Developer documentation on this model lives here: [https://developer.apple.com/documentation/security/app_sandbox/accessing_files_from_the_macos_app_sandbox](https://developer.apple.com/documentation/security/app_sandbox/accessing_files_from_the_macos_app_sandbox) It’s not a bug. It’s sandbox design. I also checked whether there’s a Mac App Store build, since sandboxed apps from the store often follow stricter entitlement patterns: [https://apps.apple.com/us/search?term=Shattle](https://apps.apple.com/us/search?term=Shattle) Didn’t see a clearly official listing under that exact name, so this appears to be a direct download distribution. ### If I Were Doing It Again I’d skip the Full Disk Access detour entirely. It wasn’t necessary and didn’t help. Instead: * Always add protected folders via the native macOS file picker. * Avoid relying on drag-and-drop for first-time folder authorization. * If permission feels stuck, remove the folder and re-add through NSOpenPanel. * Only escalate to TCC reset if the app fails to trigger a system prompt. Total time to resolve once I understood the mechanism: about 10 minutes. Time wasted assuming it was a signing issue: closer to 30. After granting proper access, performance was solid. Indexed around 1,200 files in under a minute. No unusual CPU spikes on the M2. No repeated permission logs in Console. It’s a subtle macOS behavior that doesn’t get explained in most documentation. The operating system isn’t being hostile — it’s just strict about how software asks for access. Shattle works fine. It just expects you to use the “correct” macOS pathway. Lesson logged.