Windsurf advanced troubleshooting

Windsurf Advanced Troubleshooting

Overview

Deep debugging techniques for Windsurf issues that resist standard troubleshooting. Covers Cascade context corruption, indexing engine problems, extension conflicts, MCP failures, and workspace configuration debugging.

Prerequisites

• Standard troubleshooting attempted (see windsurf-common-errors)
• Terminal access
• Understanding of Windsurf's architecture (VS Code base + Codeium AI layer)

Instructions

Step 1: Isolate Windsurf Layer vs VS Code Layer

Windsurf = VS Code + Codeium AI Layer

If the issue is:
- Editor crashes, rendering, file system → VS Code layer
- AI suggestions wrong, Cascade fails, indexing stuck → Codeium layer
- Extension not working → Extension compatibility layer

Test VS Code layer:
  windsurf --disable-extensions  # Run without extensions
  # If issue persists → VS Code layer problem

Test Codeium layer:
  # Disable Codeium: Extensions > search "codeium" > Disable
  # If issue resolves → Codeium layer problem

Step 2: Debug Cascade Context Issues

When Cascade consistently gives wrong or irrelevant suggestions:

set -euo pipefail
echo "=== Cascade Context Debug ==="

# 1. Check rules file
echo "--- .windsurfrules ---"
if [ -f .windsurfrules ]; then
  CHARS=$(wc -c < .windsurfrules)
  echo "Size: $CHARS chars (limit: 6000)"
  [ "$CHARS" -gt 6000 ] && echo "WARNING: Over limit — content truncated!"
else
  echo "MISSING — Cascade has no project context"
fi

# 2. Check workspace rules
echo "--- Workspace Rules ---"
TOTAL_RULE_CHARS=0
if [ -d .windsurf/rules ]; then
  for rule in .windsurf/rules/*.md; do
    [ -f "$rule" ] || continue
    CHARS=$(wc -c < "$rule")
    TOTAL_RULE_CHARS=$((TOTAL_RULE_CHARS + CHARS))
    HAS_TRIGGER=$(grep -c "^trigger:" "$rule" || true)
    echo "  $(basename "$rule"): $CHARS chars, trigger: $([[ $HAS_TRIGGER -gt 0 ]] && echo 'YES' || echo 'MISSING')"
  done
  echo "Total: $TOTAL_RULE_CHARS chars"
else
  echo "No .windsurf/rules/ directory"
fi

# 3. Check total rules budget
RULES_CHARS=$(wc -c < .windsurfrules 2>/dev/null || echo 0)
GLOBAL_CHARS=$(wc -c < ~/.windsurf/global_rules.md 2>/dev/null || echo 0)
TOTAL=$((RULES_CHARS + GLOBAL_CHARS))
echo "--- Total Rules Budget ---"
echo "Project rules: $RULES_CHARS + Global rules: $GLOBAL_CHARS = $TOTAL chars (limit: 12000)"
[ "$TOTAL" -gt 12000 ] && echo "WARNING: Over 12000 total — rules will be truncated!"

# 4. Check memories
echo "--- Memories ---"
MEMORY_DIR="$HOME/.codeium/windsurf/memories"
if [ -d "$MEMORY_DIR" ]; then
  MEMORY_COUNT=$(find "$MEMORY_DIR" -type f | wc -l)
  echo "Memory files: $MEMORY_COUNT"
  [ "$MEMORY_COUNT" -gt 50 ] && echo "WARNING: Many memories — may cause conflicting context"
else
  echo "No memories directory"
fi

Step 3: Debug Indexing Problems

set -euo pipefail
echo "=== Indexing Debug ==="

# Count files that would be indexed
TOTAL_FILES=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
echo "Total files (excluding node_modules, .git): $TOTAL_FILES"

# Check for large files that slow indexing
echo "--- Large files (>1MB, not in node_modules) ---"
find . -type f -size +1M -not -path '*/node_modules/*' -not -path '*/.git/*' | head -10

# Check .codeiumignore effectiveness
if [ -f .codeiumignore ]; then
  echo "--- .codeiumignore patterns ---"
  wc -l < .codeiumignore
  echo "patterns defined"
else
  echo "WARNING: No .codeiumignore — indexing everything"
fi

# Recommendations
if [ "$TOTAL_FILES" -gt 10000 ]; then
  echo ""
  echo "RECOMMENDATION: >10K files. Open a subdirectory instead of root."
  echo "RECOMMENDATION: Add more patterns to .codeiumignore"
fi

Step 4: Debug Extension Conflicts

set -euo pipefail
echo "=== Extension Conflict Check ==="

# List all installed extensions
windsurf --list-extensions 2>/dev/null | while read ext; do
  # Check for known conflicts
  case "$ext" in
    *copilot*|*tabnine*|*cody*|*intellicode*|*aws-toolkit*codewhisperer*)
      echo "CONFLICT: $ext — competes with Supercomplete/Cascade"
      ;;
    *remote*|*liveshare*|*container*)
      echo "OK: $ext — compatible but may affect performance"
      ;;
    *)
      echo "OK: $ext"
      ;;
  esac
done

echo ""
echo "Resolution: Disable conflicting extensions or run:"
echo "  windsurf --disable-extensions  # Test in clean mode"

Step 5: Debug MCP Server Issues

set -euo pipefail
echo "=== MCP Debug ==="

MCP_CONFIG="$HOME/.codeium/windsurf/mcp_config.json"
if [ -f "$MCP_CONFIG" ]; then
  echo "MCP config exists"
  # Validate JSON
  python3 -c "import json; json.load(open('$MCP_CONFIG'))" 2>&1 && echo "JSON: valid" || echo "JSON: INVALID"

  # Check each server command
  python3 -c "
import json
config = json.load(open('$MCP_CONFIG'))
for name, server in config.get('mcpServers', {}).items():
    cmd = server.get('command', 'N/A')
    print(f'  {name}: command={cmd}')
  "
else
  echo "No MCP config at $MCP_CONFIG"
fi

Step 6: Nuclear Reset Options

When nothing else works:

## Progressive Reset (least to most destructive)

1. Restart Cascade
   Command Palette > "Cascade: Restart"

2. Reset Indexing
   Command Palette > "Codeium: Reset Indexing"

3. Reload Window
   Cmd/Ctrl+Shift+P > "Developer: Reload Window"

4. Clear Memories
   Delete contents of ~/.codeium/windsurf/memories/

5. Reset All Codeium State
   Close Windsurf
   rm -rf ~/.codeium/windsurf/cache/
   Reopen Windsurf (re-indexes, re-authenticates)

6. Clean Install
   Uninstall Windsurf
   rm -rf ~/.codeium/
   rm -rf ~/.config/Windsurf/  # Linux
   # or: rm -rf ~/Library/Application Support/Windsurf/  # macOS
   Reinstall from windsurf.com/download

Error Handling

Issue	Cause	Solution
Cascade gives contradictory advice	Conflicting memories	Clear old memories
Rules ignored	Over 12K combined chars	Trim rules, check total budget
Wrong file suggestions	Stale index	Reset indexing
Slow after update	Extension incompatibility	Test with --disable-extensions
MCP tools missing	Config JSON invalid	Validate with python3 json parser
Everything broken	Corrupted state	Progressive reset (Step 6)

Examples

Quick Diagnostic One-Liner

echo "WS files: $(find . -not -path '*/node_modules/*' -not -path '*/.git/*' -type f | wc -l) | Rules: $(wc -c < .windsurfrules 2>/dev/null || echo 0)c | Ignore: $(wc -l < .codeiumignore 2>/dev/null || echo 0) patterns | Exts: $(windsurf --list-extensions 2>/dev/null | wc -l)"

Submit Support Ticket

Attach:
1. Output from all diagnostic scripts above
2. Debug bundle from windsurf-debug-bundle
3. Exact prompts that produce wrong results
4. Expected vs actual Cascade behavior

Resources

• Windsurf GitHub Issues
• Windsurf Status Page

Next Steps

For load and scale patterns, see windsurf-load-scale.