-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
nick3 edited this page May 28, 2026
·
1 revision
Symptoms and fixes for the most common failure modes. If you don't find your issue here, open one at https://github.com/mtecnic/clusterspace/issues.
- Install Visual Studio Build Tools 2022 with the "Desktop development with C++" workload.
- Open a fresh terminal after install so PATH picks up the new tooling.
- Run
npm run rebuildexplicitly to retry.
- Run
xcode-select --installand accept the EULA. - Delete
node_modules/, runnpm installagain.
- Delete
node_modules/andpackage-lock.json, reinstall from scratch.
- Vite didn't start cleanly. Check the terminal output for "address in use" — port 5173 conflict.
- Kill the stray process:
lsof -i :5173(Unix) /netstat -ano | findstr 5173(Windows).
- Was the case in older versions; if you see this, update to the latest release.
- Workaround: right-click pane → Close pane → recreate.
- The remote host doesn't have tmux installed. Either install it (
apt install tmux/brew install tmux) or switch the pane to plain SSH via the right-click menu (no tmux wrap).
- Your shell's
.bashrcauto-starts tmux. Guard it:[ -z "$TMUX" ] && tmux attach || tmux. - Or use the SSH-and-tmux to attach to the right inner session.
- Tmux/vim mouse mode is grabbing the drag. Toggle Disable App Mouse in the pane menu, or hold
Shift/Altwhile dragging.
- Was the case in very old versions; current behavior:
Ctrl+Calways SIGINTs,Ctrl+Shift+Ccopies. Update.
- The remote shell may not support bracketed paste. Disable bracketed-paste in Settings → Terminal.
- PTYs are backgrounded, not killed. Switch back to the workspace and your command is still there.
- If it's not: your PTY may have crashed independently. Check the terminal output for an exit message; click Restart Terminal.
- Verify the key path in the SSH Server manager is absolute and the key is readable.
- Test outside ClusterSpace:
ssh -i /path/to/key user@hostfrom the terminal. - Common cause on Windows: WSL path mismatch. Convert:
/mnt/c/Users/you/.ssh/id_ed25519.
- ClusterSpace injects the password by watching for
password:regex. If the server uses a non-standard prompt ("Authentication required:"), the regex misses. Workaround: switch to key auth.
- The auto-list runs
ssh host tmux list-sessionswhich requires key auth (no second password prompt). Switch to key auth, or use the manual entry field.
- They're not — the picker shows a Legacy suggestion chip with the old
fleet-term-pane-*naming. Click it to attach. - Or just
ssh host tmux lsdirectly and pick the name you want from the picker manually.
- Check DevTools for the embedded webview: right-click pane → Open DevTools. The page console will show JS errors or CORS issues.
- For Google sign-in or other strict sites, change the user-agent to a stock Chrome string (pane menu → User Agent → presets).
- Make sure the focused input is the username field. Fill flow: type username → Tab → type password. If the page doesn't auto-focus the username, click into it first.
- Verify the saved credential's origin matches the current page's origin (scheme + host).
- Check the chip rail in the status bar. Completed downloads stay until dismissed.
- Files go to your OS default downloads folder (
~/Downloads/usually). Look there.
- Bad API key. Update in AI-Providers. For Claude / OpenAI, generate a new key in their dashboard.
- Typo in the model field. Check the provider's model list (Claude:
claude-sonnet-4-5, OpenAI:gpt-4o, etc.).
- Was a regression in early versions where long conversations trimmed the original user message. Fix is in v1.0.1+. Update.
- If you see it on the current version: reduce conversation length (clear chat) and report it.
- Provider isn't running. Start Ollama / LM Studio first. Then in ClusterSpace use Discover to auto-find it.
- The model may not support tool calling. Check the provider's docs.
- For Ollama: https://ollama.com/search?c=tools lists tool-capable models.
- No active provider configured. Set one up first.
- For separate vision provider, set the
visionModelfield on the provider. For dual-purpose models (Claude, GPT-4o), leavevisionModelblank.
- Open the Goal-Dashboard. Look at the critic rail.
- If you see
critic:stuckbut the AI keeps repeating: the model isn't accepting the redirect. Either abort manually, or lowercriticIntervalStepsso the redirect fires more often. - If no critic events fire: critic is disabled (interval = 0) or interval is too high for your goal length. Reduce it.
- Check what the AI's
claim_completerationale was (visible in the dashboard step log). - For
model_questioncriteria, the judge may be too lenient. Make the question stricter ("Did all of: X, Y, AND Z happen?"). - For
manualcriteria: it trusts the rationale by design. Useshellfor strictness.
- Default is 60 minutes. For long goals, set
wallClockMshigher in the create dialog.
- Goal policy risk ceiling is too low for what the goal needs. Re-create the goal with a higher tier (e.g.,
network_writeinstead ofwrite_local), or use Allow for this goal to whitelist a tool mid-run.
- Saved window position is on a monitor you've since removed. ClusterSpace should fall back to the primary monitor automatically; if not, delete
clusterspace-window-state.json.
- Likely a corrupted
clusterspace-workspaces.json. Inspect withjq .; if obviously broken, back it up and delete.
- Was the case with old
.dialog-*class names. Fixed in current versions. Update.
- Grab the pane label (top strip), not the content area. Browser panes use the title bar; terminal panes use the tab strip area.
-
<userData>/clusterspace-data/clusterspace-browser-credentials.json. See Data-Storage-and-Migration for paths.
- They're encrypted with the source machine's OS keychain. Won't decrypt elsewhere. Re-enter them on the new machine.
- Likely you're editing the JSON files while the app is running. electron-store caches in memory and overwrites on save. Quit the app first, edit, relaunch.
- Most likely culprit:
browser-screenshots/(vision tool outputs). Wipe manually; ClusterSpace doesn't auto-clean (roadmap). - AI memory conversation history can grow too. Use the chat panel history dropdown → delete old ones.
- Broadcast mode fans out keystrokes. Disable it if not needed.
- xterm WebGL renderer should be fast — if it's not, check if your GPU has hardware acceleration enabled in Chromium (chrome://gpu in DevTools).
- For local models: small model = fast. Try
gpt-4o-miniorllama3.1:8binstead of larger ones for chat; reserve the big model for the goal runner main call. - For Claude/OpenAI: usually network latency. Check
consolein DevTools for the request timing.
- Check
Ctrl+Shift+I→ Memory tab. Likely culprits: very long conversation history, many open browser panes, large terminal scrollback. - Workaround: close idle panes, clear chat history.
- FAQ — high-frequency questions
- Installation — build/install issues
- AI-Providers — provider setup
- Goal-Runner-Overview — goal mechanics
- Data-Storage-and-Migration — file inventory and corruption recovery
ClusterSpace · Issues · Releases · MIT License · Edit any page via the Edit button (top right of the wiki).
- Workspaces-and-Layout
- Terminal-Panes
- Per-Pane-Tabs
- SSH-and-tmux
- Browser-Panes
- Saved-Logins
- Command-Palette
- Broadcast-Mode
- Settings-and-Configuration
- AI-Overview
- AI-Providers
- AI-Chat-Panel
- AI-Tools-Reference
- Personas
- Skills
- Task-Templates
- Agent-Orchestration
- Fleet-Dashboard
- Goal-Runner-Overview
- Starting-a-Goal
- Success-Criteria
- Goal-Policy-and-Risk-Levels
- Critic-and-Replan
- Vision-Verification
- Goal-Dashboard