Troubleshooting
Solutions to common problems and issues with Panopticon.WSL2 Stability Issues (Windows Users)
WSL2 can experience crashes and networking issues, especially under heavy AI agent workloads. Here are recommended.wslconfig settings to improve stability.
Recommended Configuration
Create/editC:\Users\<username>\.wslconfig:
.wslconfig:
Windows 10 Limitations
| Feature | Windows 10 | Windows 11 22H2+ |
|---|---|---|
memory, processors, swap | ✅ Works | ✅ Works |
localhostForwarding | ✅ Works | ✅ Works |
guiApplications=false | ✅ Works | ✅ Works |
networkingMode=mirrored | ❌ Not supported | ✅ Supported |
dnsTunneling=true | ❌ Not supported | ✅ Supported |
autoProxy=true | ❌ Not supported | ✅ Supported |
autoMemoryReclaim | ❌ Not supported | ✅ Supported |
sparseVhd=true | ❌ Not supported | ✅ Supported |
localhostForwarding/guiApplications settings are supported. Other settings will be silently ignored or may cause instability.
If you experience frequent WSL2 crashes on Windows 10, consider:
- Using only the basic settings shown above (memory, processors, swap, localhostForwarding, guiApplications)
- Reducing
memoryallocation if system is under pressure - Upgrading to Windows 11 for full WSL2 feature support
- Checking Windows Event Viewer for specific crash causes
Additional Windows 10 Workarounds
If NAT networking is unstable on Windows 10:- VPN clients (especially corporate VPNs)
- Docker Desktop (can conflict with WSL networking)
- Third-party firewalls
- Hyper-V virtual switch issues
"Failed to configure network (networkingMode Nat), falling back to networkingMode VirtioProxy."
References:
Slow Vite/React Frontend with Multiple Workspaces
If running multiple containerized workspaces with Vite/React frontends, you may notice CPU spikes and slow HMR. This is because Vite’s default file watching polls every 100ms, which compounds with multiple instances. Fix: Increase the polling interval in yourvite.config.mjs:
Corrupted Workspaces
A workspace can become “corrupted” when it exists as a directory but is no longer a valid git worktree. The dashboard will show a yellow “Workspace Corrupted” warning with an option to clean and recreate.Symptoms
- Dashboard shows “Workspace Corrupted” warning
git statusin the workspace fails with “not a git repository”- The
.gitfile is missing from the workspace directory
Common Causes
| Cause | Description |
|---|---|
| Interrupted creation | pan workspace create was killed mid-execution (Ctrl+C, system crash) |
| Manual .git deletion | Someone accidentally deleted the .git file in the workspace |
| Disk space issues | Ran out of disk space during workspace creation |
| Git worktree pruning | Running git worktree prune in the main repo removed the worktree link |
| Force-deleted main repo | The main repository was moved or deleted while workspaces existed |
Resolution
Via Dashboard (recommended):- Click on the issue to open the detail panel
- Click “Clean & Recreate” button
- Review the files that will be deleted
- Check “Create backup” to preserve your work (recommended)
- Click “Backup & Recreate”
Prevention
- Don’t interrupt
pan workspace createcommands - Don’t run
git worktree prunein the main repo without checking for active workspaces - Ensure adequate disk space before creating workspaces
Docker Issues
Container won’t start
”No such network: panopticon”
Permission denied on mounted volumes
If containers run as root and create files, you won’t be able to delete them:Network Issues
HTTPS not working
-
Check certificates exist:
-
Regenerate if missing:
-
Install the CA:
Can’t reach workspace URLs
-
Check Traefik is running:
-
Check DNS resolution:
- Check Traefik dashboard (http://localhost:8080) for routing rules
Agent Issues
Agent stuck / not responding
Agent keeps failing
Check the handoff count in state.json. If it’s high, the task may be too complex:- Breaking the issue into smaller tasks
- Adding more context to the issue description
- Manually handling complex parts
Messages not reaching agent
Use the proper messaging API:Workspace Issues
Workspace creation fails
Can’t delete workspace
If containers created root-owned files:Performance Issues
Dashboard slow to load
High CPU usage
- Check number of concurrent workspaces
- Increase Vite polling interval (see above)
- Run
docker statsto identify resource-heavy containers
High memory usage
Getting Help
Diagnostic Information
When reporting issues, include:Resources
- GitHub Issues: https://github.com/eltmon/panopticon/issues
- Documentation: https://www.panopticon-cli.com
- CLI Help:
pan --helporpan <command> --help
Related Guides
- Docker & HTTPS Setup - Network configuration
- Architecture - System internals
- Core Commands - CLI reference