Troubleshooting

This guide provides diagnostic procedures and solutions for common runtime, integration, and permission issues. If your symptom is not resolved by these steps, generate a diagnostics bundle for deeper analysis.

Container execution and session lifecycle

Session terminates immediately with “session ended unexpectedly”

Your organization’s managed configuration enforces requiredMinimumVersion or requiredMaximumVersion constraints that exclude Speedwave’s pinned Claude Code version. Consult your system administrator regarding supported version windows.

”WARNING: image has Claude Code X but the pinned version is Y”

An interrupted image compilation left the container image mismatched with runtime manifests. Execute speedwave update from the CLI or restart the workspace from Speedwave Desktop to trigger a clean rebuild.

Git worktree paths appear invalid on the host

Because Speedwave mounts your repository at /workspace, Git worktrees created inside the container record container-internal paths. Execute git worktree prune on the host to clean orphaned references.

Tool execution is blocked by local policies

Inspect .claude/settings.json in your repository. Claude Code enforces explicitly defined deny rules even when operating in permission-bypass mode.

Claude container terminates with exit code 137 during multi-agent workflows

Exit code 137 typically indicates an out-of-memory (OOM) termination when high subagent concurrency exceeds the fixed 6 GiB memory allocation. Reduce parallel agent count or compact conversation context. Check desktop application logs for killing a LIVE worker entries to distinguish host-initiated restarts from kernel OOM events.

Image builds fail with I/O errors in VDI or virtualized environments

Nested virtualization within corporate VDI or VMware/VirtualBox hypervisors can stall package extraction. Run speedwave check for early detection, allocate additional host RAM to the hypervisor, or verify nested VT-x/AMD-V virtualization is enabled in CPU settings.

Workspace directories inside cloud storage folders fail to open

Operating systems may restrict container mounts located inside OneDrive, Dropbox, or Google Drive sync directories. On macOS, grant access under System Settings → Privacy & Security → Files and Folders. Working directly within standard local paths is recommended to prevent filesystem lock contention.

Lima virtual machine fails to initialize (macOS)

Symptom	Resolution
`limactl not found`	Install Lima via `brew install lima` or from lima-vm.io. Speedwave requires version 0.11.0 or higher for vzNAT support.
Virtual machine stuck in `Stopping`	Execute `limactl stop --force <vm> && limactl start <vm>`.
Virtual machine not found	Re-run the initial Desktop Setup Wizard to provision the instance.
Extended initial boot time after Lima updates	Expected behavior while virtualization archives are downloaded and unpacked.

Windows installer reports “Error opening file for writing” Windows

Residual background node.exe processes from earlier versions may hold file locks on the installation directory. Exit Speedwave from the system tray, terminate orphaned node.exe processes in Windows Task Manager, and re-run the setup package.

Integration connectivity

SharePoint tools report “cannot reach oauth worker”

The host OAuth worker process may have bound to a fresh port following a watchdog recovery while the container retains cached connection parameters. Restart the project from Speedwave Desktop to update the port configuration.

macOS operating system permissions (TCC)

Helper binaries use isolated application identifiers. Click the toggle switch once and select Allow to complete the one-time migration.

System permissions were previously denied

When permission is denied on macOS 14+, the system removes the interactive toggle from system preferences. Reset the target permission bundle using tccutil:

Integration	TCC Service	Application 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`

Execute the corresponding command in terminal, then re-enable the integration toggle:

Permission dialog does not appear

A “silently rejected” error indicates macOS rejected the request without presenting a user dialog. Reset previous identifiers and reinstall the latest release:

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 reports application is not running macOS

Mail and Notes integrations automate native applications via Apple Events. If the target application is closed, macOS returns a “not found” status. Launch the application and retry the action.

For container validation errors, consult the SecurityCheck validation guide.