# Troubleshooting

Find your symptom below and use the matching fix. If it doesn't resolve things, pull the [diagnostics ZIP](/docs/guides/logs-and-diagnostics/).

## Sessions and containers

### 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

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

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

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

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

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

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)

| Symptom | Fix |
| --- | --- |
| `limactl not found` | Install from [lima-vm.io](https://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

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

### 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)

### 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

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`  |
| Mail        | `AppleEvents` | `pl.speedwave.desktop.mail`       |
| Notes       | `AppleEvents` | `pl.speedwave.desktop.notes`      |

Run the command shown, then click the toggle again and choose _Allow_.
**Caution:** Mail and Notes use the `AppleEvents` TCC service, not `Mail` or `Notes`: TCC tracks Apple Events under one service name per sender and target, so `tccutil reset Mail` resets the wrong entry.

### 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](https://github.com/speednet-software/speedwave/releases), then retry.

```
tccutil reset Calendar calendar-cli
tccutil reset Reminders reminders-cli
tccutil reset Calendar pl.speedwave.desktop.calendar
tccutil reset Reminders pl.speedwave.desktop.reminders
```

### Mail or Notes says the app is not running macOS

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](/docs/security/securitycheck/).