4d67cce6e1
- Enforced strict Node versioning with `.npmrc` engine-strict enabled ⚙️ - Declared Node.js >=20 requirement via `package.json` engines field 🚀 - Added early WSL2 environment checks during app startup 🕵️ - Introduced WSL detector utility to identify WSL and cache results 🧠 - Detects `/mnt/<drive>` Windows-mount paths to prevent common breakages 🧭 - Emits clear warnings for WSL mount risks: sockets, Electron, npm, git 🔥 - Added user-friendly WSL warning message with fix steps and docs link 📣 - Expanded installation docs with WSL2 best-practice cloning guidance 📘 - Added troubleshooting playbook for WSL2 errors and proven remedies 🛠️ - Polished File Explorer status bar styling with rounded bordered container 🎨
5.3 KiB
title, description, icon
| title | description | icon |
|---|---|---|
| Troubleshooting & Support | System logs, process monitor, debug packages, and how to get help with Maestro. | life-ring |
System Logs
Maestro maintains detailed system logs that help diagnose issues. Access them via:
- Keyboard:
Opt+Cmd+L(Mac) /Alt+Ctrl+L(Windows/Linux) - Quick Actions:
Cmd+K/Ctrl+K→ "View System Logs" - Menu: Click the hamburger menu (☰) in the Left Panel → "System Logs"
The System Log Viewer shows:
- Timestamped log entries with severity levels (info, warn, error)
- Filterable by log level and searchable text
- Real-time updates as new logs are generated
Log levels can be configured in Settings → General → System Log Level. Higher levels capture more detail but may impact performance.
Process Monitor
Monitor all running processes spawned by Maestro:
- Keyboard:
Opt+Cmd+P(Mac) /Alt+Ctrl+P(Windows/Linux) - Quick Actions:
Cmd+K/Ctrl+K→ "View System Processes" - Menu: Click the hamburger menu (☰) in the Left Panel → "Process Monitor"
The Process Monitor displays:
- All active AI agent processes and their PIDs
- Terminal/shell processes for each agent
- Process uptime and resource information
- Ability to terminate stuck processes
This is useful when an agent becomes unresponsive or you need to diagnose process-related issues.
Debug Package
If you encounter deep-seated issues that are difficult to diagnose, Maestro can generate a Debug Package — a compressed bundle of diagnostic information that you can safely share when reporting bugs.
To create a Debug Package:
- Press
Cmd+K(Mac) orCtrl+K(Windows/Linux) to open Quick Actions - Search for "Create Debug Package"
- Choose a save location for the
.zipfile - Attach the file to your GitHub issue
What's Included
The debug package collects metadata and configuration — never your conversations or sensitive data:
| File | Contents |
|---|---|
system-info.json |
OS, CPU, memory, Electron/Node versions, app uptime |
settings.json |
App preferences with sensitive values redacted |
agents.json |
Agent configurations, availability, and capability flags |
external-tools.json |
Shell, git, GitHub CLI, and cloudflared availability |
sessions.json |
Session metadata (names, states, tab counts — no conversations) |
processes.json |
Active process information |
logs.json |
Recent system log entries |
errors.json |
Current error states and recent error events |
storage-info.json |
Storage paths and sizes |
Privacy Protections
The debug package is designed to be safe to share publicly:
- API keys and tokens — Replaced with
[REDACTED] - Passwords and secrets — Never included
- Conversation content — Excluded entirely (no AI responses, no user messages)
- File contents — Not included from your projects
- Custom prompts — Not included (may contain sensitive context)
- File paths — Sanitized to replace your username with
~ - Environment variables — Only counts shown, not values (may contain secrets)
- Custom agent arguments — Only
[SET]or[NOT SET]shown, not actual values
Example path sanitization:
- Before:
/Users/johndoe/Projects/MyApp - After:
~/Projects/MyApp
WSL2 Issues (Windows)
If you're running Maestro through WSL2, most issues stem from using Windows-mounted paths. See the WSL2 installation guide for the recommended setup.
Common WSL2 Problems
"EPERM: operation not permitted" on socket binding
The Vite dev server or Electron cannot bind to ports when running from /mnt/... paths.
Solution: Move your project to the native Linux filesystem:
mv /mnt/c/projects/maestro ~/maestro
cd ~/maestro
npm install
npm run dev
"FATAL:sandbox_host_linux.cc" Electron crash
The Electron sandbox cannot operate correctly on Windows-mounted filesystems.
Solution: Run from the Linux filesystem (/home/...), not from /mnt/....
npm install timeouts or ENOTEMPTY errors
Cross-filesystem operations between WSL and Windows are unreliable for npm's file operations.
Solution: Clone and install from the Linux filesystem:
cd ~
git clone https://github.com/pedramamini/maestro.git
cd maestro
npm install
electron-rebuild failures
The Windows temp directory may be inaccessible from WSL.
Solution: Override the temp directory:
TMPDIR=/tmp npm run rebuild
Git index corruption or lock file errors
NTFS and Linux inode handling are incompatible, causing git metadata issues.
Solution: If you see "missing index" or spurious .git/index.lock errors:
rm -f .git/index.lock
git checkout -f
For new projects, always clone to the Linux filesystem from the start.
Getting Help
- GitHub Issues: Report bugs or request features
- Discord: Join the community
- Documentation: Docs site, CONTRIBUTING.md, and ARCHITECTURE.md