{"record":{"id":"1787e7e262f29e80","repo":"microsoft/typescript-go","slug":"failed-to-read-changes","errorCode":null,"errorMessage":"failed to read changes","messagePattern":"failed to read changes","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/fswatch/windows.go","lineNumber":107,"sourceCode":"//     - FILE_ACTION_ADDED / RENAMED_NEW_NAME  → events.create (→ EventUpdate)\n//     - FILE_ACTION_MODIFIED                  → events.update (→ EventUpdate)\n//     - FILE_ACTION_REMOVED / RENAMED_OLD_NAME → events.remove + tree.remove\n//  4. Call dirWatch.notify() to trigger the debouncer.\n//\n// Error recovery:\n//   - ERROR_OPERATION_ABORTED → normal shutdown (CancelIoEx was called).\n//   - ERROR_INVALID_PARAMETER → shrink buffer to 64 KB (network share limit).\n//   - ERROR_NOTIFY_ENUM_DIR  → ErrOverflow (too many changes queued).\n//   - ERROR_ACCESS_DENIED    → check if the watched dir was deleted.\n//\n// Shutdown:\n//   close(stopCh) → CancelIoEx cancels in-flight IO → run() goroutine\n//   exits → deferred CloseHandle closes the directory handle → doneCh closed.\n// ---------------------------------------------------------------------------\n\nvar (\n\terrGetFileInfo         = errors.New(\"could not get file information\")\n\terrReadChanges         = errors.New(\"failed to read changes\")\n\terrGetOverlappedResult = errors.New(\"GetOverlappedResult failed\")\n\terrUnknown             = errors.New(\"unknown error\")\n)\n\nconst (\n\tdefaultBufSize = 1024 * 1024\n\tnetworkBufSize = 64 * 1024\n\n\tnotifyChangeFilter = windows.FILE_NOTIFY_CHANGE_FILE_NAME |\n\t\twindows.FILE_NOTIFY_CHANGE_DIR_NAME |\n\t\twindows.FILE_NOTIFY_CHANGE_SIZE |\n\t\twindows.FILE_NOTIFY_CHANGE_LAST_WRITE\n)\n\n// windowsBackend.\ntype windowsBackend struct {\n\twatcherBase\n}","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/microsoft/typescript-go/blob/1bcfa18d79a3be41772223d5c05dfe4480e614ff/internal/fswatch/windows.go#L89-L125","documentation":"Error raised when the ReadDirectoryChangesW call itself fails to arm in beginRead. It surfaces two ways: synchronously from WatchDirectory when the first read armed inside subscribe fails, or via fatal() (wrapped with ErrWatchTerminated by handleWatcherError) when the next read fails inside the run loop. The sentinel does not carry the underlying Win32 error; only the fixed text is available.","triggerScenarios":"The overlapped ReadDirectoryChangesW call returns FALSE immediately: the directory handle became invalid (directory deleted, handle raced with Close), or the combination of parameters is unsupported for this filesystem/handle. Watch churn where Close and re-watch race on the same directory.","commonSituations":"Directories deleted during subscription. Network redirectors with parameter restrictions. Watch lifecycles torn down and recreated concurrently from multiple goroutines.","solutions":["If it arrives wrapped in ErrWatchTerminated, call Close() and re-subscribe once the directory is back","For subscribe-time failures, verify the directory with os.Stat and retry with backoff","Serialize watch lifecycle in your code: do not race Close() with a new WatchDirectory on the same path","Report it upstream if it reproduces against a stable local directory"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// subscribe-time:\nif err != nil && err.Error() == \"failed to read changes\" {\n    // verify the directory, then retry with backoff\n}\n// run-time (via callback):\nif errors.Is(err, fswatch.ErrWatchTerminated) {\n    // fatal read failure: Close and resubscribe when ready\n}","preventionTips":["Do not race Close() against a new WatchDirectory on the same directory","Serialize watch lifecycle transitions in your own wrapper","Verify the directory exists and is local before subscribing","Report reproducible failures against stable directories upstream"],"tags":["windows","read-directory-changes","terminal","watch-lifecycle"],"backgroundTag":null,"analyzedSha":"1bcfa18d79a3be41772223d5c05dfe4480e614ff","analyzedAt":"2026-08-16T02:12:00.115Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}