Troubleshooting Session Issues

Status: Complete
Generated: 2025-01-24 20:35 UTC
Related: Session Management Architecture Overhaul

Common Session Problems

"Claude CLI exited with code 1"

Symptom: Chat functionality completely broken, no responses from Claude
Cause: Stale session IDs in browser storage after clearing browser data
Solution: System now uses filesystem-first session recovery (fixed in architecture overhaul)

Browser Data Clearing Issues

Problem: After clearing browser data, application shows session errors
Resolution:

1. Automatic Recovery: New architecture automatically loads most recent session from filesystem
2. Manual Reset: Run /tmp/clear-sasha-storage.js in browser console if needed
3. Container Restart: Docker container restart will not affect session state

Docker Session Problems

Symptom: Sessions work locally but fail in Docker
Cause: Path encoding issues with Claude CLI project directories
Status: Fixed - Docker now uses simple project names instead of encoded paths

Permission Issues

Problem: All permissions disabled by default after updates
Cause: Permission mode incorrectly set to 'default' instead of 'bypassPermissions'
Status: Fixed - Default permissions now 'bypassPermissions' (all on by default)

Current Session Architecture (Post-Overhaul)

How It Works Now

1. Authentication: JWT-based user login (unchanged)
2. Session Source: Filesystem is authoritative source of truth
3. Initialization: Direct query to Claude CLI session files on project selection
4. Recovery: Automatic loading of most recent session if available
5. Fallback: Creates new session if none exist

Session Flow

User Login → Project Selection → Filesystem Query → Session Resolution
     ↓              ↓                    ↓               ↓
   JWT Auth    Selected Project    api.sessions()    Load/Create Session

Debugging Session Issues

Check Container Health

docker ps --filter "name=sasha"
docker logs sasha-test-container

Verify Session Files

Sessions stored in: /home/nodejs/.claude/projects/{projectName}/

Clear Browser Storage (If Needed)

Use browser console script: /tmp/clear-sasha-storage.js

Emergency Recovery

If Sessions Completely Broken

1. Container Restart:

   docker restart sasha-test-container
   

2. Clear Browser Data:

   • Clear all site data for localhost:3006
   • Refresh application

3. Check Logs:

   docker logs sasha-test-container --tail 50
   

4. Rebuild Container (if needed):

   docker stop sasha-test-container
   docker rm sasha-test-container
   docker build -f claudecodeui/Dockerfile.sliplane -t sasha-test .
   docker run -d -v sasha-workspaces:/app/workspaces -v sasha-data:/app/data -p 3006:3005 --name sasha-test-container sasha-test
   

Architecture History

Old Architecture (Pre-2025-01-24)

• Browser storage as source of truth
• Database session validation layer
• Multi-layer synchronization problems
• Fragile to browser data clearing

New Architecture (Post-2025-01-24)

• Filesystem as source of truth
• Direct Claude CLI session queries
• Self-healing session recovery
• Resilient to browser/container restarts

---

Related Documentation

• Session Management Architecture Overhaul - Complete architectural details
• Docker Development Guide - Container debugging
• Claude CLI Integration - CLI session patterns

---

For critical session issues, refer to the complete architectural documentation for in-depth understanding of the changes made during the 2025-01-24 overhaul.