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 Devin Desktop's editor, Cascade, indexing, extension, and MCP layers

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Isolate Windsurf Layer vs VS Code Layer

Devin Desktop = editor shell + Cascade + indexing/context + extension/MCP layers

If the issue is:
- Editor crashes, rendering, file system → VS Code layer
- AI suggestions wrong, Cascade fails, indexing stuck → Cascade or context/indexing 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 AI and extension layers:
  # Start with extensions disabled using the documented troubleshooting flow.
  # If the issue resolves, re-enable extensions incrementally to isolate the conflict.

Step 2: Debug Cascade Context Issues

When Cascade consistently gives wrong or irrelevant suggestions:

set -euo pipefail
echo "=== Cascade Context Debug ==="
readonly WORKSPACE_RULE_LIMIT=12000 # Current documented maximum for one workspace rule.
readonly GLOBAL_RULE_LIMIT=6000 # Current documented maximum for the global rule.

# 1. Check rules file
echo "--- .devin/rules/project.md ---"
if [ -f .devin/rules/project.md ]; then
  CHARS=$(wc -c < .devin/rules/project.md)
  echo "Size: $CHARS chars (workspace rule limit: $WORKSPACE_RULE_LIMIT)"
  [ "$CHARS" -gt "$WORKSPACE_RULE_LIMIT" ] && echo "WARNING: Workspace rule exceeds its limit"
else
  echo "MISSING — Cascade has no project context"
fi

# 2. Check workspace rules
echo "--- Workspace Rules ---"
TOTAL_RULE_CHARS=0
if [ -d .devin/rules ]; then
  for rule in .devin/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 .devin/rules/ directory"
fi

# 3. Check independent rule limits
RULES_CHARS=$(wc -c < .devin/rules/project.md 2>/dev/null || echo 0)
GLOBAL_CHARS=$(wc -c < ~/.codeium/windsurf/memories/global_rules.md 2>/dev/null || echo 0)
echo "--- Rule Limits ---"
echo "Workspace rule: $RULES_CHARS/$WORKSPACE_RULE_LIMIT chars; global rule: $GLOBAL_CHARS/$GLOBAL_RULE_LIMIT chars"
[ "$RULES_CHARS" -gt "$WORKSPACE_RULE_LIMIT" ] && echo "WARNING: Workspace rule exceeds its limit"
[ "$GLOBAL_CHARS" -gt "$GLOBAL_RULE_LIMIT" ] && echo "WARNING: Global rule exceeds its limit"

# 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
readonly LARGE_WORKSPACE_HEURISTIC=10000 # Diagnostic threshold, not a vendor limit.
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 "$LARGE_WORKSPACE_HEURISTIC" ]; 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
   Download diagnostics, then use the current indexing control in Settings.

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

4. Review Memories and Rules
   Export or record needed customizations, then remove only the confirmed bad item through the UI.

5. Re-authenticate
   Sign out and back in only after preserving diagnostics and confirming the organization.

6. Clean Install
   Follow the current support instructions for the operating system. Back up settings first; do not recursively delete the entire Codeium/Devin state tree from a generic runbook.

Output

Return a diagnostic report with the isolated failing layer, commands and evidence collected, the least-destructive corrective action, validation results, and any remaining escalation data. Redact credentials, tokens, repository content, and personal paths before sharing the report.

Error Handling

Examples

Quick Diagnostic One-Liner

echo "WS files: $(find . -not -path '*/node_modules/*' -not -path '*/.git/*' -type f | wc -l) | Rules: $(wc -c < .devin/rules/project.md 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

• Focused first-party references
• Windsurf GitHub Issues
• Windsurf Status Page

Related Skill

Continue with windsurf-load-scale when the diagnosis shows workspace size, indexing scope, or organization rollout is the limiting factor.