github-starred/actual
2
0
Fork 0
mirror of https://github.com/actualbudget/actual.git synced 2026-07-16 15:14:02 -05:00
Code Issues 3.0k Packages Projects Releases 58 Wiki Activity

[PR #7924] [CLOSED] [WIP] fix(desktop): gracefully handle EPERM in listDir on macOS #122214

New Issue
Closed
opened 2026-06-11 20:56:29 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-06-11 20:56:29 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/actualbudget/actual/pull/7924
Author: @guangyang1206
Created: 5/22/2026
Status: ❌ Closed

Base: master ← Head: fix/eperm-scandir-error-handling-7824

📝 Commits (2)

  • b1b4aa1 fix(desktop): gracefully handle EPERM in listDir on macOS
  • c3dafb3 [autofix.ci] apply automated fixes

📊 Changes

1 file changed (+17 additions, -5 deletions)

View changed files

📝 packages/loot-core/src/platform/server/fs/index.electron.ts (+17 -5)

📄 Description

On macOS, if the user denies directory permissions (e.g. Documents folder), fs.readdir() fails with EPERM,
causing the app to crash on launch.

Add a pre-check with fs.access() before readdir. If the error is EPERM, reject with a user-friendly message pointing to System Settings > Privacy & Security.

Fixes #7824

Description

Problem

On macOS, when the user denies directory permissions (e.g. the Documents folder), fs.readdir() fails with:

EPERM: operation not permitted, scandir '/Users/userdir/Documents/Actual'

Reproduction steps:

  1. Wait for the permission prompt to appear on macOS.
  2. Deny the permission.
  3. Fully close the app, then re-open it.
  4. The app can no longer open the budget file and crashes on launch.

The error is thrown in listDir() (packages/loot-core/src/platform/server/fs/index.electron.ts), which is called during budget loading before any user interaction.

Solution

Add a pre-check with fs.access() before calling fs.readdir():

export const listDir: typeof T.listDir = filepath =>
  new Promise((resolve, reject) => {
    fs.access(filepath, fs.constants.F_OK | fs.constants.R_OK, accessErr => {
      if (accessErr && (accessErr as NodeJS.ErrnoException).code === 'EPERM') {
        reject(
          new Error(
            'Permission denied: unable to access "' + filepath +
              '". Please grant Actual permission to access this folder in System Settings > Privacy & Security > Files and Folders.',
          ),
        );
        return;
      }
      fs.readdir(filepath, (err, files) => {
        if (err) {
          reject(err);
        } else {
          resolve(files);
        }
      });
    });
  });

If the error is EPERM, the user sees a clear actionable message instead of an unhandled crash.

Impact

  • ✅ App no longer crashes silently — user gets a clear permission hint
  • ✅ No behavior change when permissions are granted (happy path unchanged)
  • ✅ Only affects the Electron desktop app (index.electron.ts)
  • ✅ Error message points to the exact macOS settings path

Verification

# Simulate EPERM (macOS only)
# 1. Open Actual > trigger permission prompt > Deny
# 2. Re-open Actual
# Expected: error message with "System Settings > Privacy & Security" 
# (instead of silent crash)

Fixes #7824

Bundle Stats

Bundle Files count Total bundle size % Changed
desktop-client 33 14.01 MB 0%
loot-core 1 5.34 MB 0%
api 2 3.96 MB 0%
cli 1 7.97 MB 0%
crdt 1 11.12 kB 0%
View detailed bundle stats

desktop-client

Total

Files count Total bundle size % Changed
33 14.01 MB 0%
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger
No assets were bigger

Smaller
No assets were smaller

Unchanged

Asset File Size % Changed
static/js/index.js 2.02 MB 0%
static/js/BackgroundImage.js 121.09 kB 0%
static/js/FormulaEditor.js 962.55 kB 0%
static/js/ReportRouter.js 1.26 MB 0%
static/js/ScheduleEditForm.js 146.45 kB 0%
static/js/TransactionEdit.js 89.65 kB 0%
static/js/TransactionList.js 85.81 kB 0%
static/js/Value.js 5.08 MB 0%
static/js/bankSyncUtils.js 54.15 kB 0%
static/js/ca.js 186.78 kB 0%
static/js/chart-theme.js 800.6 kB 0%
static/js/client.js 451.37 kB 0%
static/js/da.js 101.17 kB 0%
static/js/de.js 170.58 kB 0%
static/js/en-GB.js 9.25 kB 0%
static/js/en.js 197.86 kB 0%
static/js/es.js 178.71 kB 0%
static/js/extends.js 500.57 kB 0%
static/js/fr.js 178.61 kB 0%
static/js/indexeddb-main-thread-worker-e59fee74.js 13.46 kB 0%
static/js/it.js 165.02 kB 0%
static/js/narrow.js 364.2 kB 0%
static/js/nb-NO.js 148.08 kB 0%
static/js/nl.js 106.24 kB 0%
static/js/pt-BR.js 188.46 kB 0%
static/js/resize-observer.js 18.06 kB 0%
static/js/th.js 174.48 kB 0%
static/js/theme.js 31.77 kB 0%
static/js/uk.js 207.38 kB 0%
static/js/useFormatList.js 4.96 kB 0%
static/js/wide.js 453 B 0%
static/js/workbox-window.prod.es5.js 7.33 kB 0%
static/js/zh-Hans.js 116.92 kB 0%

loot-core

Total

Files count Total bundle size % Changed
1 5.34 MB 0%
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger
No assets were bigger

Smaller
No assets were smaller

Unchanged

Asset File Size % Changed
kcab.worker.Cn6Jnyv4.js 5.34 MB 0%

api

Total

Files count Total bundle size % Changed
2 3.96 MB 0%
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger
No assets were bigger

Smaller
No assets were smaller

Unchanged

Asset File Size % Changed
index.js 3.96 MB 0%
models.js 0 B 0%

cli

Total

Files count Total bundle size % Changed
1 7.97 MB 0%
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger
No assets were bigger

Smaller
No assets were smaller

Unchanged

Asset File Size % Changed
cli.js 7.97 MB 0%

crdt

Total

Files count Total bundle size % Changed
1 11.12 kB 0%
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger
No assets were bigger

Smaller
No assets were smaller

Unchanged

Asset File Size % Changed
index.js 11.12 kB 0%

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/actualbudget/actual/pull/7924 **Author:** [@guangyang1206](https://github.com/guangyang1206) **Created:** 5/22/2026 **Status:** ❌ Closed **Base:** `master` ← **Head:** `fix/eperm-scandir-error-handling-7824` --- ### 📝 Commits (2) - [`b1b4aa1`](https://github.com/actualbudget/actual/commit/b1b4aa16e47921daf140d2caecd30cfe5f2be50c) fix(desktop): gracefully handle EPERM in listDir on macOS - [`c3dafb3`](https://github.com/actualbudget/actual/commit/c3dafb389d7e8fb3ffb089b29d0bcfd62d59f7d0) [autofix.ci] apply automated fixes ### 📊 Changes **1 file changed** (+17 additions, -5 deletions) <details> <summary>View changed files</summary> 📝 `packages/loot-core/src/platform/server/fs/index.electron.ts` (+17 -5) </details> ### 📄 Description On macOS, if the user denies directory permissions (e.g. Documents folder), fs.readdir() fails with EPERM, causing the app to crash on launch. Add a pre-check with fs.access() before readdir. If the error is EPERM, reject with a user-friendly message pointing to System Settings > Privacy & Security. Fixes #7824 <!-- Thank you for submitting a pull request! Make sure to follow the instructions to write release notes for your PR — it should only take a minute or two: https://actualbudget.org/docs/contributing/#writing-good-release-notes. Try running yarn generate:release-notes *before* pushing your PR for an interactive experience. --> ## Description ### Problem On **macOS**, when the user denies directory permissions (e.g. the **Documents** folder), `fs.readdir()` fails with: ``` EPERM: operation not permitted, scandir '/Users/userdir/Documents/Actual' ``` **Reproduction steps:** 1. Wait for the **permission prompt** to appear on macOS. 2. **Deny** the permission. 3. Fully close the app, then re-open it. 4. The app can no longer open the budget file and crashes on launch. The error is thrown in `listDir()` (`packages/loot-core/src/platform/server/fs/index.electron.ts`), which is called during budget loading before any user interaction. ### Solution Add a **pre-check with `fs.access()`** before calling `fs.readdir()`: ```ts export const listDir: typeof T.listDir = filepath => new Promise((resolve, reject) => { fs.access(filepath, fs.constants.F_OK | fs.constants.R_OK, accessErr => { if (accessErr && (accessErr as NodeJS.ErrnoException).code === 'EPERM') { reject( new Error( 'Permission denied: unable to access "' + filepath + '". Please grant Actual permission to access this folder in System Settings > Privacy & Security > Files and Folders.', ), ); return; } fs.readdir(filepath, (err, files) => { if (err) { reject(err); } else { resolve(files); } }); }); }); ``` If the error is `EPERM`, the user sees a **clear actionable message** instead of an unhandled crash. ### Impact - ✅ App no longer crashes silently — user gets a clear permission hint - ✅ No behavior change when permissions are granted (happy path unchanged) - ✅ Only affects the Electron desktop app (`index.electron.ts`) - ✅ Error message points to the exact macOS settings path ### Verification ```bash # Simulate EPERM (macOS only) # 1. Open Actual > trigger permission prompt > Deny # 2. Re-open Actual # Expected: error message with "System Settings > Privacy & Security" # (instead of silent crash) ``` Fixes #7824 <!--- actual-bot-sections ---> <hr /> <!--- bundlestats-action-comment key:combined start ---> ### Bundle Stats Bundle | Files count | Total bundle size | % Changed ------ | ----------- | ----------------- | --------- desktop-client | 33 | 14.01 MB | 0% loot-core | 1 | 5.34 MB | 0% api | 2 | 3.96 MB | 0% cli | 1 | 7.97 MB | 0% crdt | 1 | 11.12 kB | 0% <details> <summary>View detailed bundle stats</summary> #### desktop-client **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 33 | 14.01 MB | 0% <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** No assets were bigger **Smaller** No assets were smaller **Unchanged** Asset | File Size | % Changed ----- | --------- | --------- static/js/index.js | 2.02 MB | 0% static/js/BackgroundImage.js | 121.09 kB | 0% static/js/FormulaEditor.js | 962.55 kB | 0% static/js/ReportRouter.js | 1.26 MB | 0% static/js/ScheduleEditForm.js | 146.45 kB | 0% static/js/TransactionEdit.js | 89.65 kB | 0% static/js/TransactionList.js | 85.81 kB | 0% static/js/Value.js | 5.08 MB | 0% static/js/bankSyncUtils.js | 54.15 kB | 0% static/js/ca.js | 186.78 kB | 0% static/js/chart-theme.js | 800.6 kB | 0% static/js/client.js | 451.37 kB | 0% static/js/da.js | 101.17 kB | 0% static/js/de.js | 170.58 kB | 0% static/js/en-GB.js | 9.25 kB | 0% static/js/en.js | 197.86 kB | 0% static/js/es.js | 178.71 kB | 0% static/js/extends.js | 500.57 kB | 0% static/js/fr.js | 178.61 kB | 0% static/js/indexeddb-main-thread-worker-e59fee74.js | 13.46 kB | 0% static/js/it.js | 165.02 kB | 0% static/js/narrow.js | 364.2 kB | 0% static/js/nb-NO.js | 148.08 kB | 0% static/js/nl.js | 106.24 kB | 0% static/js/pt-BR.js | 188.46 kB | 0% static/js/resize-observer.js | 18.06 kB | 0% static/js/th.js | 174.48 kB | 0% static/js/theme.js | 31.77 kB | 0% static/js/uk.js | 207.38 kB | 0% static/js/useFormatList.js | 4.96 kB | 0% static/js/wide.js | 453 B | 0% static/js/workbox-window.prod.es5.js | 7.33 kB | 0% static/js/zh-Hans.js | 116.92 kB | 0% </div> </details> --- #### loot-core **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 1 | 5.34 MB | 0% <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** No assets were bigger **Smaller** No assets were smaller **Unchanged** Asset | File Size | % Changed ----- | --------- | --------- kcab.worker.Cn6Jnyv4.js | 5.34 MB | 0% </div> </details> --- #### api **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 2 | 3.96 MB | 0% <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** No assets were bigger **Smaller** No assets were smaller **Unchanged** Asset | File Size | % Changed ----- | --------- | --------- index.js | 3.96 MB | 0% models.js | 0 B | 0% </div> </details> --- #### cli **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 1 | 7.97 MB | 0% <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** No assets were bigger **Smaller** No assets were smaller **Unchanged** Asset | File Size | % Changed ----- | --------- | --------- cli.js | 7.97 MB | 0% </div> </details> --- #### crdt **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 1 | 11.12 kB | 0% <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** No assets were bigger **Smaller** No assets were smaller **Unchanged** Asset | File Size | % Changed ----- | --------- | --------- index.js | 11.12 kB | 0% </div> </details> </details> <!--- bundlestats-action-comment key:combined end ---> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-06-11 20:56:29 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
AI generated
API
bank sync
budgeting
bug
can’t replicate
dependencies
docker
documentation
electron
experimental feature
feature
feedback
goal templates
good first issue
help wanted
importers
maintenance
needs info
needs testing
needs triage
needs votes
openid
payees
pull-request
Mirrored from GitHub Pull Request
 regression
reports
responsive
rules
schedules
server
✨ merged
split transactions
tech debt
tech-support
theme
transaction import
transaction reconciliation
transactions
translations
upstream
user interface
✅ approved
wontfix
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/actual#122214
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?