Ide connection issues

CURSOR_IDE_TROUBLESHOOTING.md

@@ -0,0 +1,111 @@
+# Cursor IDE Connection Issues - Troubleshooting Guide
+
+## Issue Summary
+
+Analysis of Cursor IDE logs from 2026-01-29 reveals several interconnected issues causing instability and connection problems.
+
+## Root Causes Identified
+
+### 1. WSL File Watcher Incompatibility (Primary Cause)
+
+**Symptoms:**
+- Repeated errors: `Failed to watch \\wsl.localhost\... for changes using fs.watch()`
+- `EISDIR: illegal operation on a directory` errors
+- `EUNKNOWN` errors when reading file changes
+
+**Cause:**
+Windows `fs.watch()` API does not work reliably with WSL2 network paths (`\\wsl.localhost\...`). This is a known limitation when running Cursor on Windows while accessing files stored in WSL.
+
+**Solutions:**
+1. **Recommended**: Open the project directly from within WSL using Cursor's Remote-WSL extension
+   - In Cursor, use `Remote-WSL: New Window` command
+   - Navigate to your project at `/home/nhayfield/work/siris-os-2`
+
+2. **Alternative**: Move the project to Windows filesystem (e.g., `C:\Users\nathan.hayfield\projects\`)
+   - Note: This may have performance implications for WSL-based tooling
+
+3. **Workaround**: Add problematic paths to Cursor's file watcher exclusions:
+   - Open Settings (`Ctrl+,`)
+   - Search for `files.watcherExclude`
+   - Add patterns for large directories or paths causing issues
+
+### 2. Extension Host Crashes
+
+**Symptoms:**
+- `Extension host terminated unexpectedly`
+- Exit code `-1073740791` (STATUS_STACK_BUFFER_OVERRUN)
+- Affected extensions: `anysphere.cursor-always-local`, `anysphere.cursor-retrieval`
+
+**Cause:**
+Stack buffer overflow in extension host process, likely triggered by WSL path handling issues or memory pressure.
+
+**Solutions:**
+1. Clear Cursor's extension cache:
+   - Close Cursor
+   - Delete `%APPDATA%\Cursor\CachedExtensionVSIXs`
+   - Delete `%USERPROFILE%\.cursor\extensions` (backup first if needed)
+   - Restart Cursor
+
+2. Increase Node.js memory limit (if applicable):
+   - Set environment variable: `NODE_OPTIONS=--max-old-space-size=4096`
+
+3. Disable problematic extensions temporarily to isolate the issue
+
+### 3. OpenTelemetry/Telemetry Errors
+
+**Symptoms:**
+- `OTLPExporterError: Bad Request`
+- `Trace spans collection is not enabled for this user`
+
+**Cause:**
+Cursor's telemetry backend rejecting trace data. This is typically benign but may indicate authentication or network issues.
+
+**Solutions:**
+1. This error is generally ignorable
+2. If persistent, check your Cursor subscription status
+3. Verify network connectivity to `api2.cursor.sh`
+
+### 4. Sidebar State Corruption
+
+**Symptoms:**
+- Repeated `Index out of bounds` errors for sidebar visibility checks
+
+**Cause:**
+Corrupted workspace state data.
+
+**Solutions:**
+1. Reset workspace state:
+   - Close Cursor
+   - Delete the workspace storage folder:
+     `%APPDATA%\Cursor\User\workspaceStorage\6239da4cf3b495bd1622c805b4771005`
+   - Restart Cursor
+
+2. Reset all Cursor settings (last resort):
+   - Backup your settings first
+   - Delete `%APPDATA%\Cursor\User\settings.json`
+
+## Quick Fix Checklist
+
+- [ ] Use Remote-WSL extension instead of accessing WSL paths from Windows
+- [ ] Clear extension cache
+- [ ] Reset workspace storage for affected workspace
+- [ ] Update Cursor to latest version
+- [ ] Ensure WSL2 is up to date (`wsl --update`)
+- [ ] Check available system memory
+
+## Preventive Measures
+
+1. **For WSL development**: Always use Remote-WSL connection mode
+2. **Avoid cross-filesystem access**: Don't access WSL files from Windows paths or vice versa
+3. **Keep Cursor updated**: Check for updates regularly
+4. **Monitor extensions**: Disable extensions you don't actively use
+
+## Additional Resources
+
+- [Cursor Documentation](https://cursor.sh/docs)
+- [WSL Best Practices](https://docs.microsoft.com/en-us/windows/wsl/filesystems)
+- [VS Code Remote Development](https://code.visualstudio.com/docs/remote/wsl)
+
+---
+
+*Generated from log analysis on 2026-01-29*