Troubleshooting
Find your symptom below and use the matching fix. If it doesn’t resolve things, pull the diagnostics ZIP.
Sessions and containers
Section titled “Sessions and containers”Chat ends right away with “session ended unexpectedly”
Section titled “Chat ends right away with “session ended unexpectedly””Your org’s requiredMinimumVersion/requiredMaximumVersion excludes Speedwave’s pinned Claude Code version. Ask your admin which versions are allowed.
”WARNING: image has Claude Code X but the pinned version is Y” in the logs
Section titled “”WARNING: image has Claude Code X but the pinned version is Y” in the logs”An interrupted rebuild left the claude image out of sync. Run speedwave update, or restart the project from Desktop.
A worktree Claude made looks broken on the host
Section titled “A worktree Claude made looks broken on the host”The container mounts your project at /workspace, so a worktree Claude creates inside records paths that don’t exist on the host. Run git worktree prune there.
A tool call is blocked and it isn’t Speedwave
Section titled “A tool call is blocked and it isn’t Speedwave”Check .claude/settings.json before blaming Speedwave. Claude Code applies its deny rules even in bypass-permissions mode.
The claude container exits with code 137 during multi-agent runs
Section titled “The claude container exits with code 137 during multi-agent runs”Code 137 usually means an OOM kill: a wide agent fan-out can exceed the fixed 6 GiB budget. Run fewer agents in parallel, or shorten the conversation. Check the Desktop log for killing a LIVE worker first: if present, it’s a host-side restart, not an OOM kill.
Image builds hang or fail with I/O errors inside a corporate VDI or VMware/VirtualBox VM
Section titled “Image builds hang or fail with I/O errors inside a corporate VDI or VMware/VirtualBox VM”Nested virtualization can stall package unpacking during the build. speedwave check warns you up front, and a failed build retries. Still stuck? Give the VM more RAM, or enable nested VT-x in the host hypervisor.
A project directory inside OneDrive, Dropbox, or Google Drive won’t open
Section titled “A project directory inside OneDrive, Dropbox, or Google Drive won’t open”macOS can block access to cloud-synced folders. If you see Cloud storage permission required, open System Settings > Privacy & Security > Files and Folders, enable Speedwave, then Retry. Prefer a local directory: cloud sync churn can corrupt the workspace mount.
The Lima VM won’t start (macOS)
Section titled “The Lima VM won’t start (macOS)”| Symptom | Fix |
|---|---|
limactl not found | Install from lima-vm.io or brew install lima. Speedwave needs 0.11.0+, for vzNAT and gvproxy. |
Stuck in Stopping | limactl stop --force <vm> && limactl start <vm> |
| VM not found | Re-run the Speedwave.app setup wizard. |
| Slow first start after a Lima update | Normal: it’s downloading a container-tooling archive. |
Speedwave.exe won’t reinstall, or says “Error opening file for writing” Windows
Section titled “Speedwave.exe won’t reinstall, or says “Error opening file for writing” ”Orphaned node.exe processes can block the installer on v0.11 and earlier (v0.12+ cleans these up). Close Speedwave from the tray, end remaining node.exe in Task Manager, then reinstall.
Integration connectivity
Section titled “Integration connectivity”SharePoint tools fail with “cannot reach oauth worker”
Section titled “SharePoint tools fail with “cannot reach oauth worker””The host-side oauth worker rotated its loopback port, often after a watchdog respawn, and the SharePoint container still points at the old one. Restart the project from Desktop to fix it.
OS integration permissions (macOS TCC)
Section titled “OS integration permissions (macOS TCC)”An integration is disabled with a banner after upgrading
Section titled “An integration is disabled with a banner after upgrading”Each helper now has its own identifier, so your old grant no longer applies. Click the toggle once and choose Allow. It’s a one-time migration.
Permission was previously denied
Section titled “Permission was previously denied”Once you’ve clicked Don’t Allow, macOS 14 removes the button to re-add a permission by hand. The toggle instead shows a tccutil reset command.
| Integration | TCC service | Identifier |
|---|---|---|
| Calendar | Calendar | pl.speedwave.desktop.calendar |
| Reminders | Reminders | pl.speedwave.desktop.reminders |
AppleEvents | pl.speedwave.desktop.mail | |
| Notes | AppleEvents | pl.speedwave.desktop.notes |
Run the command shown, then click the toggle again and choose Allow.
The consent dialog never appears
Section titled “The consent dialog never appears”A “silently rejected” message means macOS rejected the request without a dialog, usually a damaged install. Clear the TCC entries below, reinstall from GitHub Releases, then retry.
tccutil reset Calendar calendar-clitccutil reset Reminders reminders-clitccutil reset Calendar pl.speedwave.desktop.calendartccutil reset Reminders pl.speedwave.desktop.remindersMail or Notes says the app is not running macOS
Section titled “Mail or Notes says the app is not running ”Mail and Notes drive the host app through Apple Events, so if it isn’t open, macOS reports “not found” rather than a permission error. Open it and click the toggle again.
If none of these match what you’re seeing, also check SecurityCheck.