diff --git a/apps/oxfmt/src-js/cli.ts b/apps/oxfmt/src-js/cli.ts
index 4fca3dea4a569..ea924e972a19e 100644
--- a/apps/oxfmt/src-js/cli.ts
+++ b/apps/oxfmt/src-js/cli.ts
@@ -16,13 +16,17 @@ void (async () => {
   const args = process.argv.slice(2);
 
   // Node.js sets non-TTY `stdio` to non-blocking mode,
-  // which causes `WouldBlock` errors in Rust when writing large output with `--stdin-filepath`.
-  // https://github.com/oxc-project/oxc/issues/17939 (issue was on macOS)
-  //
+  // which causes `WouldBlock` errors in Rust.
   // As a workaround, if used with pipe, set blocking mode before calling NAPI bindings.
   // See: https://github.com/napi-rs/napi-rs/issues/1630
+  //
+  // stdout: Writing large formatted output via `--stdin-filepath` can overflow the pipe buffer.
+  // https://github.com/oxc-project/oxc/issues/17939 (observed on macOS)
   // @ts-expect-error: `_handle` is an internal API
   if (!process.stdout.isTTY) process.stdout._handle?.setBlocking?.(true);
+  // stdin: In LSP mode (`--lsp`), VSCode communicates via stdin/stdout pipes.
+  // Rust reads stdin expecting blocking I/O, but non-blocking mode returns `EAGAIN` (os error 11).
+  // https://github.com/oxc-project/oxc/issues/20285
   // @ts-expect-error: `_handle` is an internal API
   if (!process.stdin.isTTY) process.stdin._handle?.setBlocking?.(true);