Troubleshooting
Fixes for common Daintree 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 | On a packaged install, reinstall Daintree: the native PTY module has been built against the wrong runtime. If you're running from source, npm run rebuild rebuilds it. See Build from Source. |
| 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. Settings > Troubleshooting > Run health check confirms whether Git, Node, and npm are visible to Daintree at all. |
| Blank window / UI won't load | Check the logs for main-process errors. Launching Daintree from a terminal with DAINTREE_DEBUG=1 set gives verbose output. See Accessing Logs. |
| 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 it. The app restarts. See Hardware Acceleration. |
| Auto-update not working | Auto-update runs in packaged builds only, and is off entirely for Windows Store, Flatpak, and Snap builds, and for Linux builds without an AppImage or package marker. See When Auto-Update Is Disabled. |
| An update downloaded but you're still on the old version | Daintree notices this on the next launch and raises an "Update didn't install" toast with a Download manually action. On macOS a reinstall from a fresh download is usually the only fix. See Updates. |
| PTY resize glitches | Enable Performance mode in Settings > Terminal. It simplifies the rendering pipeline. |
| Stale UI / rendering issues from source | Delete node_modules/.vite to clear the Vite cache, then restart the dev server. |
| Low disk space warning or critical toast | Daintree monitors the volume holding its application data, which isn't necessarily your system drive. The warning fires below 2000 MB; below 500 MB it goes critical, and session backups and terminal snapshots pause until space is available. Free space on that volume. See Disk space. |
| Panels feel slow or the UI lags | Close idle panels and lower Scrollback history in Settings > Terminal. On lower-end hardware, turn on Performance mode. Then open the Diagnostics Dock's Why slow? tab, which names what's actually consuming resources rather than leaving you to guess. |
| Daintree is using a lot of memory | Open the memory badge in the sidebar first. It splits Daintree's own memory from the dev servers, agents, and tools your terminals launched, and the second number is usually the larger one. To reclaim, use Free memory on a background project in the project switcher, or turn on Auto-close idle projects in Settings > General. See Automatic Resource Management. |
| Cannot add more panels (creation blocked) | You've hit the panel hard limit. Go to Settings > Terminal > Panel limits and raise the hard limit, or click Reset to hardware-recommended defaults. |
| A background project closed itself | Auto-close idle projects is on and the project had no terminals open past its idle threshold. Reopen it from the switcher; its panels come back. Raise the threshold or turn the setting off in Settings > General. |
| Project in a cloud-synced folder causes terminal or git errors | Cloud sync corrupts the git index and interferes with terminal I/O, and it breaks worktrees outright. 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 enters safe mode after three unclean exits inside a 30-minute sliding window. The banner reads "Safe mode: panels weren't restored". After five in the same window, auto-relaunch is disabled and you launch the app yourself. See Safe Mode. |
| "Terminal service restarting" banner / terminal output stopped | The pty-host process 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 Restart service, click that. See Terminal Service Crashes. |
| "Crash watchdog disabled" banner | The deadlock detector gave up after repeated restart failures: Daintree itself is fine. What you lose is the automatic kill of 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 caught a render-time exception in that surface. The rest of the app keeps working. Copy the Error ID for the bug report, then reopen the affected dialog or panel, or reload the renderer from the Help menu. 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. |
| "File watching degraded" toast (Linux) | The inotify watch limit is exhausted, so Daintree has fallen back to polling for that worktree. Raise fs.inotify.max_user_watches to get instant updates back. macOS reaches the same state through the file-descriptor ceiling. See Linux: File Watching Degraded. |
| "Reconnecting…" spinner in the sidebar | The workspace host process exited. It's project-scoped and owns git state, file watching, and worktree operations. Daintree restarts it automatically, up to three attempts with backoff, and the spinner clears on its own. You only need to act if "Workspace host crashed and could not recover" appears. See Workspace Host Crashes. This is a different process from the terminal pty-host above. |
Dig Deeper
When the quick fix above isn't enough, the mechanics live on three subpages:
- Diagnostics Dock: the six tabs (Problems, Logs, Events, Telemetry, Perf, and Why slow?) plus the sidebar memory badge, collecting and redacting a diagnostics bundle, the hardware-acceleration toggle and GPU fallbacks, and the cloud-synced folder warning.
- Crash Recovery & Safe Mode: how Daintree detects and classifies unclean exits, the safe-mode crash-loop guard, the recovery dialog and auto-restore, the pre-crash action trail, the deadlock watchdog, and terminal and workspace host crashes.
- Performance & Logs: resource profiles and what they change, memory pressure and the ways to reclaim memory, disk-space monitoring, Linux file watching, error boundaries, developer mode, and 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 (Settings > General), your operating system, the relevant log output, and a diagnostics bundle. The bundle already carries the version, platform, GPU state, and recent logs, and the review dialog lets you strip anything you'd rather not publish before it's written. For a crash specifically, the recovery dialog's Report this crash builds the report for you, action trail included, and shows it to you before you submit it.