[Kitenite]

Problem

Seven Sentry issues (3+2+1+1+1+1+1 events, release 1.19.0) from a single user environment: filesystem.listDirectory fails with ETIMEDOUT errno errors (scandir/lstat timing out) and surfaces them as reported INTERNAL_SERVER_ERROR 500s. The user's repository lives on a network-backed/virtual filesystem mount where these syscalls can time out — an environmental failure, not an app bug.

Root cause

The desktop filesystem router's withFsErrorTranslation maps known user-environment errnos to typed non-500 TRPCErrors via ERRNO_TO_TRPC, but ETIMEDOUT was not in the map, so it fell through to the rethrow-and-report path.

All seven issues cross this same boundary: every event is tagged trpc_path: filesystem.listDirectory. The lstat-on-individual-file variants come from Node's fs.readdir(..., { withFileTypes: true }), which falls back to a per-entry lstat when the filesystem returns unknown dirent types (typical of virtual/network mounts) — still inside the same translated listDirectory call.

Fix

Classification only (per the PR #6164 contract — no beforeSend filter, no Sentry-side suppression):

• Add ETIMEDOUT to FsErrnoCode in apps/desktop/src/shared/fs-error-types.ts
• Map it to TIMEOUT in ERRNO_TO_TRPC in apps/desktop/src/lib/trpc/routers/filesystem/index.ts

Error messages are preserved verbatim; unrecognized errnos still rethrow and stay reported 500s. Sibling errnos (ENOTCONN, EIO) were deliberately not added: EIO can indicate genuine disk/hardware failure that must keep reporting, and ENOTCONN has not been observed — no evidence to justify pre-classifying either.

Verification

$ bunx biome check apps/desktop/src/shared/fs-error-types.ts apps/desktop/src/lib/trpc/routers/filesystem/index.ts
Checked 2 files in 13ms. No fixes applied.

$ cd apps/desktop && bun run typecheck
$ tsc --noEmit
(exit 0)

No existing tests cover these files; none were touched.

Refs DESKTOP-NT
Refs DESKTOP-NN
Refs DESKTOP-NY
Refs DESKTOP-NS
Refs DESKTOP-NR
Refs DESKTOP-NQ
Refs DESKTOP-NP

https://claude.ai/code/session_48e2c6bd-dc88-43af-8756-7d63377c3318

---

Summary by cubic

Classifies ETIMEDOUT filesystem errors as TIMEOUT in the Desktop filesystem TRPC router instead of 500. This prevents false INTERNAL_SERVER_ERROR reports for filesystem.listDirectory on network/virtual mounts and aligns with DESKTOP-NT, DESKTOP-NN, DESKTOP-NY, DESKTOP-NS, DESKTOP-NR, DESKTOP-NQ, DESKTOP-NP.

^{Written for commit e88e562. Summary will update on new commits.}

Summary by CodeRabbit

• Bug Fixes
  • Improved handling of filesystem timeouts.
  • Network and virtual filesystem timeout errors now display as standard timeout errors instead of generic failures.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f908d5c4-3b59-48fe-880d-ef714a639693

📥 Commits

Reviewing files that changed from the base of the PR and between 31fb0fc and e88e562.

📒 Files selected for processing (2)

• apps/desktop/src/lib/trpc/routers/filesystem/index.ts
• apps/desktop/src/shared/fs-error-types.ts

---

📝 Walkthrough

Walkthrough

The filesystem error type now accepts ETIMEDOUT. The filesystem TRPC router maps this errno to the TIMEOUT error code.

Changes

Filesystem timeout handling

Layer / File(s)	Summary
Add ETIMEDOUT support apps/desktop/src/shared/fs-error-types.ts, apps/desktop/src/lib/trpc/routers/filesystem/index.ts	The FsErrnoCode union includes ETIMEDOUT. The filesystem router maps it to the TRPC TIMEOUT code.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• superset-sh/superset#6164: Extends filesystem error translation and FsErrnoCode definitions.

Suggested reviewers: saddlepaddle

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses conventional commit format and clearly describes classifying ETIMEDOUT filesystem errors as TIMEOUT.
Description check	✅ Passed	The description explains the problem, root cause, fix, scope, verification steps, and test results, but it omits the template headings and checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sentry/desktop-fs-etimedout-classify

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

No issues found across 2 files

Architecture diagram

sequenceDiagram
    participant Client as Desktop Client
    participant TRPC as tRPC Router
    participant FsRouter as Filesystem Router
    participant FsErr as withFsErrorTranslation
    participant OS as OS Filesystem

    Note over Client,OS: filesystem.listDirectory call flow

    Client->>TRPC: tRPC request: filesystem.listDirectory
    TRPC->>FsRouter: listDirectory()
    FsRouter->>OS: fs.readdir() with { withFileTypes: true }

    alt Normal filesystem
        OS-->>FsRouter: Directory entries
        FsRouter-->>Client: Success response
    else Network/virtual mount timeout
        OS-->>FsRouter: ETIMEDOUT errno
        FsRouter->>FsRouter: Catch error with errno ETIMEDOUT
        FsRouter->>FsErr: Translate error
        FsErr->>FsErr: Lookup ERRNO_TO_TRPC map
        alt ETIMEDOUT in map (NEW behavior)
            FsErr-->>FsRouter: TRPCError with code "TIMEOUT"
            FsRouter-->>Client: 408 TIMEOUT response (non-500)
        else errno not in map (OLD behavior)
            FsErr->>FsErr: Fall through to rethrow
            FsErr-->>FsRouter: Error rethrown
            FsRouter-->>Client: 500 INTERNAL_SERVER_ERROR
            FsRouter->>TRPC: Report to Sentry
        end
    end

    Note over FsErr: ERRNO_TO_TRPC mapping targets:<br/>EACCES → FORBIDDEN<br/>EPERM → FORBIDDEN<br/>ENOSPC → PRECONDITION_FAILED<br/>ETIMEDOUT → TIMEOUT (NEW)

Loading

_{Re-trigger cubic}

[github-actions]

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

• ⚠️ Neon database branch

Thank you for your contribution! 🎉