Troubleshooting

Start with Settings → Diagnostics. Confirm the desktop interface, bundled OpenCode runtime, and event stream are healthy before changing credentials or reinstalling the app.

The app is still starting

• Wait for the bundled OpenCode status to change from Starting to Running.
• If it does not, quit normally and reopen the app.
• Check Diagnostics for an unclean previous shutdown or a recorded runtime failure.
• Do not start a separate opencode serve process for the app.

Provider or model problems

• Open Settings → Providers and confirm the provider is connected.
• Wait for the real provider catalog to finish loading.
• Reconnect if a credential was revoked or expired.
• Confirm the provider account can use the selected model.
• Try another model from the same connected provider to isolate model-specific eligibility.

A task is not updating

The event stream can temporarily fall back to polling. Check Settings → Diagnostics → Event stream. If tasks continue but the UI is stale, refresh Diagnostics and switch away from and back to the session.

Computer Use cannot see or control an app

• Confirm the operating system meets the Computer Use requirements.
• Open Settings → Computer Use and rerun the setup check.
• Verify the platform accessibility and application-window capture services. On macOS, review macOS permissions. On Windows, check UI Automation and window capture. On Ubuntu, check AT-SPI, PipeWire, and the XDG ScreenCast portal.
• Select the intended application again and keep its windows available.
• Stop immediately if the preview targets the wrong app.

Dictation records no text

• Confirm the Whisper Dictation Extension is enabled.
• Confirm the model download is complete and verified.
• Verify microphone permission.
• Try a longer recording with clear speech and low background noise.

Remote will not pair or reconnect

• Keep the desktop app running and online.
• Generate a new pairing request if five minutes have passed.
• To pair the native iPhone or iPad companion, open its Scan pairing code action and scan from inside the app. Scanning with the system Camera app opens Remote Web instead.
• Approve the pending device on the desktop.
• Confirm Remote is enabled and its service grant is current.
• Revoke and pair again if the device identity was reset.

An approved native companion normally reconnects from its iOS Keychain credential after the app closes or the device restarts. Remote Web normally reconnects from the same browser profile. Private browsing may discard browser storage when the private session ends, so use a normal browser profile when the pairing must persist.

If the desktop still lists a device as Offline while the companion asks to pair, the companion no longer has the matching credential. Revoke the stale desktop entry, create one new pairing offer, and approve the replacement device.

An update cannot restart

Finish active tasks and close running project terminals. Return to Settings → Updates and try Update and restart again after the blocker clears.

If the issue remains, export a diagnostic report and contact support.