Troubleshooting

Common Issues

Diagnostics Dock

The Diagnostics Dock is a resizable panel that sits at the bottom of the Canopy window. It brings together three diagnostic views (Problems, Logs, and Events) into a single tabbed interface, giving you a unified place to monitor errors, log output, and IPC events.

The toolbar carries an AlertCircle badge button that turns red with a dot indicator when undismissed errors exist. Clicking it toggles the dock open or closed. You can also open the dock through keyboard shortcuts or the action palette.

All four actions are also available through the action palette (Cmd+Shift+P): search for "Toggle Diagnostics", "Show Problems", "Show Logs", or "Show Events". For the full shortcut reference, see Keyboard Shortcuts.

Problems Tab

The Problems tab shows active app errors in a table with columns for time, type, message, source, and actions. Each error is categorised by type: Git, Process, File, Network, Config, or Other.

Click any row to expand its details, which shows the full error information in a preformatted block. The expanded view includes a Copy button that copies the complete error text (message, type, timestamp, source, details, and context) to your clipboard.

Some errors display a recovery hint with a lightbulb icon, suggesting how to resolve the issue. Transient errors also show a Retry button that re-attempts the failed operation. Every row has a Dismiss button (×) to remove it from the active list.

The toolbar for the Problems tab provides two actions:

• Open Logs opens the raw log file in your system text editor
• Clear All dismisses every active error at once

Logs Tab

The Logs tab displays a virtualised, real-time log stream from the Electron main process. A filter bar at the top lets you narrow entries by log level and source.

Auto-scroll keeps the view pinned to the latest entry by default. Toggle it off to pause scrolling and review older entries. When auto-scroll is off and you're not at the bottom, a floating "Scroll to bottom" button appears.

Toolbar actions for the Logs tab:

• Auto-scroll toggle (highlighted when active)
• Open File opens the log file in your system editor
• Clear clears the log buffer

Events Tab

The Events tab shows a live IPC event timeline in a split layout. The left side lists events in chronological order, and the right side shows the full detail of the selected event. A filter bar at the top lets you narrow down the event stream.

This tab is useful for debugging timing issues between processes, inspecting event payloads, and understanding how different parts of the app communicate.

The toolbar provides a Clear action that wipes the event buffer. A confirmation dialog appears before clearing to prevent accidental data loss.

Resizing the Dock

The dock has a drag handle along its top edge. Drag it up to increase height or down to decrease it. The default height is 256px, with a minimum of 128px and a maximum of 50% of the viewport height.

For keyboard access, tab to the resize handle and use ArrowUp/ArrowDown to adjust the height in 10px steps. Your preferred height is saved automatically and restored the next time you open the dock.

Download Diagnostics

When filing a bug report or troubleshooting a tricky issue, a diagnostics report gives you (and anyone helping) a complete snapshot of your system state. Go to Settings > Troubleshooting and click Download Diagnostics.

Canopy collects data across 12 sections and saves it as a JSON file. A native Save dialog appears with a default filename of canopy-diagnostics-{timestamp}.json. The report includes:

• App metadata (version, Electron, Chrome, Node.js versions)
• Runtime (platform, architecture, paths, environment variables)
• Operating system (type, version, CPU, memory, load average)
• Display (all monitors with bounds, scale factor, rotation)
• GPU (hardware acceleration status, feature flags)
• Process (memory and CPU usage, Electron process metrics)
• Tools (availability and version of git, node, npm, npx, gh)
• Git config (configuration with sensitive values redacted)
• App config (selected store keys, deep-redacted)
• Terminals (active PTY sessions with IDs and state)
• Logs (last 100 log entries)
• Events (last 100 IPC events)

Hardware Acceleration

The Hardware Acceleration toggle is the first setting in Settings > Troubleshooting. Toggling it restarts the app immediately with GPU rendering enabled or disabled.

Disabling Manually

If you see blank panels, black screens, or persistent rendering glitches, try disabling hardware acceleration. The setting shows "Disable if you experience blank panels or rendering issues. App will restart." After toggling off, Canopy relaunches with GPU rendering disabled.

Automatic Disable After GPU Crashes

After three GPU process crashes in a single session, Canopy writes a flag file and relaunches automatically with hardware acceleration disabled. The setting subtitle will show "GPU was disabled due to repeated crashes. Re-enable to restore full performance. App will restart."

The flag persists across launches. Re-enabling via the toggle clears it and restarts the app.

Safe Mode

Safe mode is triggered automatically when Canopy detects a crash loop. There is no manual trigger.

What Triggers It

If Canopy crashes three times within 60 seconds of each launch, it boots in safe mode on the next start. Safe mode skips restoring panel and workspace state, which prevents a corrupted session from causing another crash. A yellow banner appears at the top of the app:

"Safe mode — the app booted without restoring panels due to repeated crashes."

After five rapid crashes, Canopy also disables auto-relaunch as a further guard. There's no additional UI for this state beyond the banner already shown at three crashes.

Returning to Normal

Once the app runs cleanly for five minutes, the crash counter resets automatically. Safe mode ends on the next launch with no action required.

Cloud-Synced Folder Warning

Canopy checks whether your project sits inside a cloud-synced folder when you open it. If the project path falls under a known sync location for iCloud Drive, Dropbox, OneDrive, or Google Drive, a persistent warning toast appears with the title Cloud Sync Folder Detected. The toast names the specific service and stays visible until you dismiss it.

Why this matters

Cloud sync services and git use incompatible file access models. Running a git repository inside a synced folder can cause real problems:

• Lock file conflicts — Git uses .git/index.lock for mutual exclusion. Sync daemons grab locks on these files, causing Unable to create '.git/index.lock': File exists errors during normal git operations.
• Index and ref corruption — Sync clients observe intermediate write states and create conflict copies (e.g. index (conflicted copy)). These silently corrupt the repository state, and branch refs can revert without warning.
• I/O bottlenecks — Operations like git checkout, git rebase, or npm install mutate thousands of files rapidly. Sync daemons try to process every filesystem event in real time, causing CPU spikes and noticeable slowdowns in terminal output.

Dismissing the warning

Click Don't Show Again on the toast to suppress the warning for that specific project. Canopy saves this preference to the project's settings, so the warning won't appear again when you reopen it.

Detected paths

Canopy checks the following paths to determine whether a project is inside a cloud-synced folder. Entries with * are prefix patterns — the provider may append an account name or organization suffix to the folder name.

If you see the warning, move the project to a local folder outside these paths (e.g. ~/Projects/ or ~/Developer/). Use a git remote on GitHub, GitLab, or a similar service for cross-machine access instead of filesystem sync.

Accessing Logs

Canopy keeps a log file with app activity, errors, and diagnostic info.

View Logs

• Go to Settings > Troubleshooting > Open Log File to open the log in your system text editor
• Use Clear Logs to reset the log file

Verbose Logging

For more detailed output, enable verbose logging:

• Session-only: toggle Verbose Logging in Settings > Troubleshooting (resets on restart)
• Persistent: set the environment variable CANOPY_DEBUG=1 before launching Canopy

Download Diagnostics

The Download Diagnostics button in Settings > Troubleshooting (above the Developer Mode section) exports a full diagnostic snapshot. A native Save dialog opens and the file is saved as canopy-diagnostics-<timestamp>.json.

The export contains 12 sections: metadata, runtime, OS, display, GPU, process, tools, git, config, terminals, logs, and events. Each section has a five-second collection timeout (two seconds for GPU). All file paths are sanitised, sensitive keys (token, password, secret, apiKey, and similar) are redacted, and the hostname is replaced with <hostname>.

Developer Mode

Enable Developer Mode in Settings > Troubleshooting to access debugging tools:

• Auto-Open Diagnostics opens the Diagnostics Dock automatically on launch
• Focus Events Tab defaults to the Events tab in the Diagnostics Dock when it auto-opens

DevTools

Access Chromium DevTools with Cmd+Alt+I (macOS) or Ctrl+Shift+I (Windows/Linux). DevTools are available in development builds by default. In production builds, enable Developer Mode first.

Performance Profiling

If you're running from source, there are performance testing scripts available:

• npm run perf:smoke — quick smoke test
• npm run perf:ci — CI performance run
• npm run perf:nightly — nightly performance run
• npm run perf:soak — extended soak test
• npm run stress-test — TUI stress test

Set CANOPY_PERF_CAPTURE=1 before starting Canopy to enable internal performance capture mode.

Automatic Resource Management

Canopy manages memory, disk, and CPU in the background. Understanding these systems can help when something seems off.

Adaptive Profiles

Canopy selects a Performance, Balanced, or Efficiency internal profile based on available memory, battery state, and open worktree count. The profile adjusts polling frequency and how aggressively idle projects are hibernated. There is no manual override. If you notice slower UI updates or quicker project hibernation, it likely means the Efficiency profile is active. Closing unused worktrees or plugging in the charger will reduce the pressure score and shift back to Balanced or Performance.

Memory Pressure Response

When memory pressure is detected, Canopy first clears caches and releases hidden webviews. If pressure persists across three consecutive intervals, it hibernates idle projects. A 10-minute cooldown prevents the same project from being repeatedly hibernated. If terminal output pauses briefly during high-volume bursts, the PTY host resource governor is throttling output to protect heap stability. It resumes within 10 seconds.

Disk Space Monitoring

Canopy watches the application data volume every 5 minutes. A warning toast appears when free space drops below 500 MB. Below 100 MB, a persistent critical toast appears and session backups are paused to stop consuming disk. Free space on the application data volume to restore normal operation. If you're unsure which volume that is, check the path shown in Settings > Troubleshooting > Open Log File.

Crash Recovery

Canopy automatically detects unclean exits and offers to restore your session on the next launch. A lock file (running.lock) is written when the app starts and removed on a clean shutdown. If the lock file is still present at the next startup, Canopy knows the previous session ended unexpectedly.

Your session state is backed up to disk every 60 seconds, and also whenever an agent finishes a task or transitions to a waiting state. This means you rarely lose more than a minute of layout changes, even after a hard crash.

Recovery Dialog

When Canopy detects a previous crash, it shows a recovery dialog before loading the workspace. The dialog displays the crash timestamp and lists every panel from your last session backup.

Each panel in the list shows its type (agent, terminal, browser, notes, Dev Preview), title, working directory, and last known agent state. You can check or uncheck individual panels to control exactly which ones get restored. A "Select all / Deselect all" toggle at the top makes bulk selection quick.

Panels that were created within 30 seconds of the crash are flagged as "suspects" with a warning icon. These panels may have contributed to the crash, so you can deselect them while still restoring everything else.

Two primary actions are available: Restore selected (which restores only the checked panels) and Start fresh (which discards the backup and opens a clean workspace). If no panel list is available in the backup, the dialog shows simpler card-style buttons for "Restore Previous Session" and "Start Fresh" instead.

Error Details and Crash Reporting

The recovery dialog includes a collapsible Error Details section. Expanding it reveals diagnostic information: app version, platform, OS version, session duration, Electron version, memory statistics, panel count, and (when available) the error message and stack trace.

Inside Error Details you'll find two buttons. Open log file opens the crash log JSON in your system text editor. Report this crash uses a two-step flow: the first click shows a privacy disclosure (crash reports may include file paths from your working directories), and the second click copies a formatted markdown report to your clipboard and opens GitHub Issues in your browser. You then paste the report into a new issue.

Auto-Restore

The recovery dialog includes a checkbox labelled "Don't show this again — always restore automatically". When enabled, future crashes bypass the dialog entirely and silently restore all panels from the backup. To turn it off again, go to Settings > Troubleshooting and disable the Auto-Restore on Crash toggle.

Safe Mode

If Canopy crashes three times within 60 seconds, the crash loop guard activates safe mode. In safe mode the app starts without restoring any panels, and a yellow banner appears at the top of the window reading "Safe mode — the app booted without restoring panels due to repeated crashes."

Safe mode gives you a stable, clean session to investigate what went wrong. If the app stays running for five minutes without another crash, the crash counter resets automatically and normal behavior resumes on the next launch.

After five crashes, automatic relaunch is disabled entirely to prevent an infinite restart loop. At that point you'll need to launch Canopy manually.

GPU Crashes

Canopy monitors the GPU process separately. If the GPU process crashes three times in a single session, hardware acceleration is automatically disabled and the app relaunches. This prevents persistent GPU driver issues from making Canopy unusable.

When hardware acceleration has been disabled, the Settings > Troubleshooting > Hardware Acceleration toggle shows "Hardware Acceleration Disabled — GPU was disabled due to repeated crashes." You can re-enable it from there; the app will restart with hardware acceleration turned back on.

Renderer Crashes

Separate from full application crashes, the Chromium renderer process can crash while Canopy is running. These are handled independently from the main crash recovery system.

On the first renderer crash, Canopy automatically reloads the window and shows a toast notification confirming the reload. If the renderer crashes repeatedly within 60 seconds, Canopy loads a recovery page with two options: Reload Window (tries loading the full UI again) and Reset Workspace State (clears the workspace and starts fresh).

Out-of-memory crashes follow the same pattern. The first OOM crash destroys and recreates the window, while repeated OOM crashes trigger the recovery page.

Crash Files and Session Backups

The session backup captures your panel list, working directories, last agent state for each panel, and window layout. This is the data used to restore your workspace after a crash.

Crash logs and backup files are stored in the Canopy user data directory:

Within that directory, the relevant files are:

• running.lock — crash detection marker (present while Canopy is running)
• crashes/ — crash log files in JSON format (up to 10 retained, older logs pruned automatically)
• backups/session-state.json — the most recent session backup (updated every 60 seconds)

For more on how Canopy persists session state during normal operation, see Session Management.

Getting Help

If you're stuck:

• GitHub Issues — report bugs and request features
• GitHub Discussions — ask questions and share tips

When reporting an issue, include your Canopy version (from Settings > General), operating system, relevant log output, and a diagnostics report from Settings > Troubleshooting.