Troubleshooting
Common issues and how to resolve them.
Workspace Issues
“Session not found”
# List available sessions
isolate list
# Check where you are
isolate whereami
“Workspace already exists”
# Use --idempotent to succeed if already exists
isolate work feature-123 --idempotent
“Detached HEAD”
This shouldn’t happen with JJ, but if it does:
# Check current state
jj status
# See the current commit
jj log -r @
# Create a new change if needed
jj new
Sync Issues
“Sync failed”
# Try again with verbose output
isolate sync --verbose
# Check for conflicts
jj status
jj diff
Conflicts during sync
# See what conflicts exist
jj status
# Resolve manually
vim <conflicted-file>
# Commit the resolution
jj describe -m "resolve: merge conflicts"
JJ Issues
“jj: command not found”
Install JJ:
# Via cargo
cargo install jj-cli
# Via Homebrew
brew install jj
“Cannot lock”
# Check what's locking
jj log
# Force unlock if needed (rare)
# JJ handles this automatically
Exit Codes
| Code | Meaning | What to Do |
|---|---|---|
| 0 | Success | Done |
| 1 | Validation error | Check input syntax |
| 2 | Not found | Check session/task name |
| 3 | System error | Check system resources |
| 4 | External command error | Check JJ installation |
| 5 | Lock contention | Try again later |
Getting Help
# Check isolate version
isolate --version
# Get help for a command
isolate <command> --help
# Check context
isolate context
Common Patterns
Start Fresh
isolate whereami # Should return "main"
isolate work feature-auth --idempotent
Continue Existing Work
isolate whereami # Returns "workspace:feature-auth"
# Already in workspace, continue working
Abandon and Start Over
isolate abort --dry-run # Preview
isolate abort # Execute
isolate work feature-auth-v2 # Start fresh
Prevention
- Run
isolate syncregularly — Don’t let main get too far ahead - Use
--idempotentwhen retrying — Prevents “already exists” errors - Check
isolate whereamibefore operations — Know where you are - Use
isolate contextfor full status — See everything at once