Troubleshooting
Fixes for common issues, plus pointers to the Diagnostics Dock, crash recovery and safe mode, and performance, file watching, and logs.
Common Issues
| Problem | Solution |
|---|---|
| Terminal fails to start / PTY spawn error | The native PTY module is built against the wrong Electron version and needs rebuilding. Run npm run rebuild from the project source, or reinstall Daintree. |
| Agent CLI not detected | The CLI has to be on your PATH. Open a system terminal and run which claude (macOS/Linux) or where claude (Windows). If nothing comes back, reinstall the agent, then restart Daintree. |
| Blank window / UI won't load | Check the logs for main process errors. On macOS, launch Daintree from Terminal with DAINTREE_DEBUG=1 set to get verbose output. |
| Blank panels or black screen rendering | Hardware acceleration was either auto-disabled after a GPU crash or needs disabling by hand. Go to Settings > Troubleshooting > Hardware Acceleration and toggle the setting. The app restarts. See Hardware Acceleration. |
| Auto-update not working | Auto-update only runs in packaged builds (DMG/NSIS/AppImage/DEB). Development builds don't support it, and Windows Store builds update through the Microsoft Store instead. See Updates for the full details. |
| PTY resize glitches | Enable Performance Mode in Settings > Terminal. It simplifies the rendering pipeline. |
| Stale UI / rendering issues | If you're running from source, delete node_modules/.vite to clear the Vite cache, then restart the dev server. |
| Gemini CLI display issues | Gemini uses an alternate screen buffer, and Daintree handles that case specifically. If you still see rendering problems, restart the Gemini panel. |
| Low disk space warning or critical toast | Daintree monitors the application data volume, which isn't necessarily your system drive. Free up space on that volume to get back to normal operation. Below the critical threshold of 100 MB, session backups pause automatically and resume once space is available. See Disk Space Monitoring. |
| Panels feel slow or UI lags | Close idle panels and lower the Scrollback History setting in Settings > Terminal. On lower-end hardware, enable Performance Mode. If Resource Monitoring is on, check per-panel CPU and memory in the panel headers to find the heavy processes. |
| Cannot add more panels (creation blocked) | You've hit the panel hard limit. Go to Settings > Terminal > Performance > Panel Limits and raise the Hard Limit, or click Reset to hardware-recommended defaults. |
| Project hibernated unexpectedly | Under memory pressure, Daintree hibernates idle projects automatically to free resources. Reopen the project from the sidebar and relaunch the terminals you need. If it keeps happening, close unused worktrees or run fewer agents at once. See Automatic Resource Management. |
| Project in a cloud-synced folder causes terminal or git errors | Cloud sync can corrupt the git index and interfere with terminal I/O. Move the project to a local directory outside OneDrive, Dropbox, iCloud, and Google Drive. See Cloud-Synced Folder Warning. |
| App crashes repeatedly on launch | Daintree activates safe mode automatically after three unclean exits inside a 30-minute sliding window. The banner reads "Safe mode — panels weren't restored". After five crashes in the same window, auto-relaunch is disabled and you'll have to launch the app yourself. See Safe Mode. |
| "Terminal service restarting" banner / terminal output stopped | The pty-host UtilityProcess that owns terminal I/O exited, and Daintree is restarting it. The banner clears on its own once the restart succeeds. If it switches to an error variant with a Restart service button, click that to bring the backend back. See Terminal Service Crashes. |
| "Crash watchdog disabled" banner | The deadlock-detection watchdog gave up after repeated restart failures. The app still works; you just lose automatic SIGKILL on a frozen main process. Click Restart watchdog in the banner to resume monitoring. See Crash Watchdog. |
| A section of the UI shows "Something went wrong" with an Error ID | An Error Boundary around that surface caught a render-time exception. The rest of the app keeps working. Copy the Error ID for the bug report, then use Help > Reload or reopen the affected dialog or panel. See When Parts of the UI Fail. |
| macOS dialog: "Daintree would like to access files in your [folder]" | A CLI agent running inside Daintree is asking for access to a protected folder: Desktop, Documents, Downloads, a removable drive, a network share, or a cloud-synced folder. Click Allow to grant it. macOS attributes the request to Daintree because the agent runs inside Daintree's process tree. To review or revoke access later, open System Settings > Privacy & Security > Files and Folders. See macOS Folder Access for the full explanation. |
| "File watching degraded" toast (Linux) | The Linux inotify watch limit is exhausted, so Daintree has fallen back to periodic polling for that worktree. Raise fs.inotify.max_user_watches to get instant file updates back. See Linux: File Watching Degraded. |
| "Reconnecting…" spinner in the sidebar | The workspace host process exited unexpectedly. It's project-scoped and owns git state, file watching, and worktree ops. Daintree surfaces the crash within ~10 ms and restarts the host automatically, up to three attempts with exponential backoff. You don't need to do anything unless the fatal error "Workspace host crashed and could not recover" appears. See Workspace Host Crashes. This is a different process from the terminal pty-host covered in Terminal Service Crashes. |
Dig Deeper
When the quick fix above isn't enough, the detailed mechanics live on three subpages:
- Diagnostics Dock: the Problems, Logs, and Events tabs, downloading a diagnostics bundle, the hardware-acceleration toggle and GPU fallbacks, and the cloud-synced folder warning.
- Crash Recovery & Safe Mode: how Daintree detects unclean exits, the safe-mode crash-loop guard, the recovery and auto-restore flow, the deadlock watchdog, and terminal and workspace host crashes.
- Performance & Logs: developer mode and DevTools, automatic resource management, Linux inotify file watching, section-level error boundaries, and accessing logs.
Getting Help
If you're stuck:
- GitHub Issues: report bugs and request features
- GitHub Discussions: ask questions and share tips
When you report an issue, include your Daintree version (from Settings > General), your operating system, the relevant log output, and a diagnostics bundle from Settings > Troubleshooting.