Windsurf Cascade Stuck? 5 Tested Fixes for Freezing, Spinning, and Internal Errors

Overview

Windsurf’s Cascade — its agentic AI assistant capable of multi-file edits, terminal commands, and self-correcting code execution — occasionally gets stuck. The symptoms vary: an infinite spinner after generating a plan, a blank panel, a cryptic “internal error” message, or the IDE itself freezing. This article covers five tested fixes, ordered from fastest to most involved, along with the root causes behind each failure mode.

What Causes Cascade to Get Stuck

There is no single failure mode. Cascade can stall for at least four distinct reasons:

Context window overflow. Long conversations fill the context window. Once it overflows, earlier context gets silently dropped, and Cascade starts looping or producing incoherent edits. Windsurf added a visual context-window indicator for this reason — watch it.

gRPC processing bottleneck. The renderer thread processes gRPC responses synchronously. With 70+ queued responses, the JavaScript event loop blocks entirely and the UI freezes. This is a known architectural issue (GitHub issue #284).

Terminal detection failure. Cascade watches for command completion in the integrated terminal. If it cannot detect that a command finished — because of a custom shell prompt, missing default terminal profile, or a fancy zsh theme — it hangs waiting indefinitely.

Provider-side errors. Upstream model providers (Anthropic, OpenAI) return 429 (rate limit) or 503 (service unavailable) errors that Cascade surfaces as:

Error: Cascade has encountered an internal error in this step. No credits consumed on this tool call.

Solution 1: Start a Fresh Conversation

This fixes context overflow — the most common cause.

Cascade limits conversation history and degrades as sessions grow long. If you have been working in the same Cascade thread for more than 15–20 exchanges, the context window is likely saturated.

1. Click the + button in the Cascade panel to start a new conversation.
2. Re-state your task in a single, focused prompt. Reference specific files by name rather than saying “the file we were working on.”
3. If your project is large, add a .windsurfignore file to exclude irrelevant directories:

node_modules/
.git/
dist/
build/
*.min.js

This reduces the context Cascade indexes, giving it more room for actual reasoning.

Why this works: A fresh conversation resets the context window to zero. Combined with .windsurfignore, you prevent the window from refilling with noise from generated files and dependency directories.

Solution 2: Clear the Cascade Cache and Restart

This fixes cache corruption and stale session state.

Windsurf stores Cascade session data and cached model responses locally. Corruption here causes blank panels, repeated “internal error” messages, and phantom spinner states that persist across new conversations.

macOS:

rm -rf ~/Library/Caches/Windsurf
rm -rf ~/.codeium/windsurf/cascade

Windows (PowerShell):

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Windsurf\Cache"
Remove-Item -Recurse -Force "$env:USERPROFILE\.codeium\windsurf\cascade"

Linux:

rm -rf ~/.cache/Windsurf
rm -rf ~/.codeium/windsurf/cascade

If the problem persists after clearing cache, also try signing out of your Codeium account (bottom-left avatar → Sign Out), then signing back in. This forces a full session re-authentication and can resolve token-related failures silently masked as “internal errors.”

Solution 3: Fix Terminal Profile and Shell Theme Conflicts

This fixes Cascade hanging after running terminal commands.

Cascade executes shell commands in Windsurf’s integrated terminal and watches for the prompt to return before proceeding. Two configurations break this detection:

Missing default terminal profile. If no default is set, Cascade cannot reliably spawn or monitor shell sessions.

Fix: Open Settings (Ctrl + , on Windows/Linux, ⌘ + , on macOS) → search terminal.integrated.defaultProfile → select a profile for your OS (e.g., bash, zsh, PowerShell).

Custom zsh themes. Themes like Powerlevel10k, Starship, and some Oh My Zsh themes output non-standard escape sequences that prevent Cascade from detecting command completion.

To test whether your theme is the culprit:

# Temporarily disable your zsh theme
# In ~/.zshrc, comment out the theme line:
# ZSH_THEME="powerlevel10k/powerlevel10k"

# Then restart Windsurf (not just the terminal)

If Cascade works with the theme disabled, you have two options: keep the theme disabled inside Windsurf only (by checking for the TERM_PROGRAM environment variable in your .zshrc), or switch to a simpler theme for Windsurf’s terminal:

# Add to ~/.zshrc
if [[ "$TERM_PROGRAM" == "windsurf" ]]; then
  ZSH_THEME="robbyrussell"  # or any minimal theme
else
  ZSH_THEME="powerlevel10k/powerlevel10k"
fi

Solution 4: Check for Provider Errors and Switch Models

This fixes upstream model outages and rate limiting.

Cascade routes requests to external model providers. When those providers are overloaded or down, Cascade fails silently or throws generic internal errors. Before debugging your own setup, check Codeium’s status page.

To see the actual error codes:

1. Open Help → Toggle Developer Tools in Windsurf.
2. Switch to the Network tab.
3. Trigger a Cascade request and look for HTTP 429 (rate limit) or 503 (service down) responses.

If you see rate-limit errors, either wait 60 seconds or switch to a different model. Cascade supports multiple backend models — if Claude is failing, try GPT-4o, and vice versa. This is not a quality judgment; it is a routing workaround. Each provider has independent availability.

Solution 5: Fix the UI Freeze (gRPC Bottleneck)

This fixes the IDE itself becoming unresponsive — not just the Cascade panel.

When Cascade processes a large multi-file edit, the renderer can lock up entirely: no scrolling, no clicking, no keyboard input. This is distinct from Cascade spinning — the whole editor freezes.

The root cause is synchronous gRPC message processing on the main thread. There is no user-side configuration to fix this; it requires a Windsurf update. However, you can reduce the likelihood:

• Reduce request scope. Ask Cascade to edit one file at a time instead of “refactor the entire module.”
• Close unused editor tabs. Each open tab adds to the renderer workload during Cascade operations.
• Disable unnecessary extensions. Extensions that hook into file-change events (formatters, linters with watch mode) compound the gRPC backlog.

If the IDE is already frozen, wait 30–60 seconds — the queue usually drains. Force-quitting loses unsaved changes.

Still Not Working?

If none of these fixes resolve the issue:

1. Update Windsurf to the latest version. Codeium ships fixes frequently and does not maintain a public changelog for every patch.
2. File a bug on the Codeium GitHub issues page. Include your OS, Windsurf version (Help → About), and the output from Developer Tools.
3. Check the Windsurf Discord — the #bugs channel often has workarounds before they hit official docs.
4. Try the Windsurf web app as a temporary workaround — it bypasses local cache and terminal issues entirely.

FAQ