Repository navigation
desktop: macOS app silently denied ~/Documents (missing NSDocumentsFolderUsageDescription) -> empty model selector #56479
Description
Summary
On macOS, the OpenCode desktop app cannot use a workspace located under ~/Documents (also affects ~/Desktop / ~/Downloads). The app does not declare NSDocumentsFolderUsageDescription in its Info.plist, so macOS silently denies access with EPERM instead of showing an "Allow" prompt. Every location-scoped API call then returns HTTP 500, leaving the model selector empty and preventing the workspace from loading.
Environment
- opencode version: desktop app 2.0.32 (bundled CLI 2.0.32, Electron 44.4.5). Note: a separate Homebrew
opencodeonPATHreports v2.0.18. - OS: macOS 26.6.2 (build 25G83), Darwin 25.6.0, arm64 (Apple Silicon)
- Terminal: N/A for this issue (desktop app). Reported from WezTerm.
- Shell: /bin/zsh
- Install/channel: release (
latestauto-update channel) - Active plugins: none found in config
Reproduction
- On macOS, make sure the app has no Documents access: System Settings → Privacy & Security → Full Disk Access → disable/remove OpenCode. (Do not grant Files and Folders → Documents either.)
- Launch the OpenCode desktop app on a workspace under
~/Documents, e.g./Users/<user>/Documents/Default Project. - Open the model selector.
Expected Behavior
The workspace loads and the model selector lists the configured models (providers opencode and opencode-go). If the OS needs permission, macOS shows a prompt to allow access to the Documents folder.
Actual Behavior
All requests scoped to that workspace return HTTP 500, e.g. GET /api/model, GET /api/provider, GET /api/config, GET /api/location, GET /api/fs/list, and the session endpoints:
PlatformError: Unknown: FileSystem.realPath (/Users/<user>/Documents/Default Project)
[cause]: Error: EPERM: operation not permitted, lstat '/Users/<user>/Documents/Default Project'
The model selector is empty. No permission prompt was ever shown. The same endpoints return HTTP 200 with a full model list when the workspace is outside the protected folders (e.g. /Users/<user>).
Additional Context
- From the app's process context,
ls ~/DocumentsreturnsOperation not permitted. /Applications/OpenCode.app/Contents/Info.plisthas noNSDocumentsFolderUsageDescription. Per macOS TCC rules, a missing usage string means the system does not prompt and the access is denied silently, so the app never appears under "Files and Folders" for the user to allow.- Workaround that fixed it: grant OpenCode Full Disk Access (System Settings → Privacy & Security → Full Disk Access), then fully quit (⌘Q) and relaunch the app. After that, the Documents workspaces load and the model selector populates.
- Alternatively, using a workspace outside
~/Documents,~/Desktop, or~/Downloadsworks with no permission change. - Reproducible 100% until Full Disk Access is granted.
- Suggestions: add
NSDocumentsFolderUsageDescription(and likelyNSDesktopFolderUsageDescription/NSDownloadsFolderUsageDescription) to the app'sInfo.plistso macOS prompts normally; and show a clear error in the UI when the workspace can't be read instead of an empty model list.
Activity
opencode-agent commentedon Oct 17, 2026
Thanks for the detailed report and the workaround. I couldn't reproduce this here, because it needs the macOS desktop app and macOS's privacy (TCC) behaviour, and this environment is Linux only. A maintainer with a Mac will need to confirm it.
I did check the build config. In both v2.0.32 and the latest
dev(8c173a8), the macOSextendInfoinpackages/desktop/electron-builder.config.tsonly setsNSAutoFillRequiresTextContentTypeForOneTimeCodeOnMac. It has noNSDocumentsFolderUsageDescription,NSDesktopFolderUsageDescriptionorNSDownloadsFolderUsageDescription, which matches what you found inInfo.plist.Related:
EPERMon~/Documents) make requests fail with HTTP 500 and the app doesn't explain whyUntil then, your workaround works: grant Full Disk Access (or use a workspace outside
~/Documents,~/Desktopand~/Downloads), then quit and relaunch the app.argszero commentedon Oct 17, 2026
I'd like to work on this — the missing usage descriptions, which is the first half of what you suggest.
At
devthe macOSextendInfoinpackages/desktop/electron-builder.config.tsdeclares onlyNSAutoFillRequiresTextContentTypeForOneTimeCodeOnMac, so I will addNSDocumentsFolderUsageDescription,NSDesktopFolderUsageDescriptionandNSDownloadsFolderUsageDescriptionthere — the app can open a workspace from any of the three folders, so all three need a string or TCC denies silently in each.packages/desktop/electron-builder.config.test.tsalready asserts the existingNSAutoFill…key, so I will extend that assertion to cover the folder descriptions, which makes the change checkable without a Mac and without a build.I cannot exercise the TCC prompt or a packaged app from here, so the PR will say that plainly rather than claim a macOS verification it did not run. I will leave the second half — explaining an unreadable workspace in the UI instead of showing an empty model list — alone, since #50952 is already open on that direction.
dajiaohuang commentedon Oct 22, 2026
Thanks for the focused macOS change and config test in #56608. Its close note says it was closed only for the contributor open-PR cap and the branch remains available; this issue is still open. Could you reopen the PR or confirm the branch is no longer current? I'll avoid a duplicate. The PR also records that packaged macOS/TCC prompt validation remains for a maintainer with a Mac; I am not claiming that validation.