Troubleshooting Guide¶

Common issues when using Shannot and their solutions.

PyPy Sandbox Issues¶

"PyPy sandbox not found"¶

Symptoms:

Error: PyPy sandbox binary not found

Solutions:

Run the setup command:
```
shannot setup runtime
```
Check if pypy-sandbox is in PATH:
```
which pypy-sandbox
```

Specify path explicitly:

shannot run --pypy-sandbox /path/to/pypy-sandbox script.py

"Runtime not installed"¶

Symptoms:

Error: Runtime not installed. Run 'shannot setup runtime' first.

Solution:

# Install runtime
shannot setup runtime

# Force reinstall
shannot setup runtime --force

# Check status
shannot setup runtime --status

"lib-python not found"¶

Symptoms:

Error: lib-python directory not found at expected location

Solution:

# Reinstall runtime
shannot setup runtime --force

# Or specify path explicitly
shannot run --lib-path /path/to/runtime script.py

Python 3.6 Compatibility¶

Syntax Errors¶

Symptoms:

SyntaxError: invalid syntax

Cause: Using Python 3.7+ syntax in sandboxed scripts.

Common Issues:

Match statements (Python 3.10+)

# NOT SUPPORTED
match value:
    case 1: print("one")

# Use instead
if value == 1:
    print("one")

Union type syntax (Python 3.10+)

# NOT SUPPORTED
def process(x: int | str): pass

# Use instead
from typing import Union
def process(x: Union[int, str]): pass

Walrus operator (Python 3.8+)

# NOT SUPPORTED
if (n := len(items)) > 10: pass

# Use instead
n = len(items)
if n > 10: pass

dataclasses (Python 3.7+)

# NOT SUPPORTED
from dataclasses import dataclass
@dataclass
class Point:
    x: int
    y: int

# Use instead
from collections import namedtuple
Point = namedtuple('Point', ['x', 'y'])

Module Not Found¶

Symptoms:

ModuleNotFoundError: No module named 'xxx'

Cause: Third-party modules are not available in the sandbox.

Solution: Only use Python 3.6 stdlib modules. The sandbox does not have pip access.

Session Issues¶

"Session not found"¶

Symptoms:

Error: Session 'xxx' not found

Causes: 1. Session ID is incorrect 2. Session has expired (1-hour TTL) 3. Session was already executed

Solutions:

# List all sessions
shannot approve list

# Check session history
shannot approve history

# Create new session
shannot run script.py

"Session expired"¶

Symptoms:

Error: Session 'xxx' has expired

Cause: Sessions expire after 1 hour.

Solution: Create a new session:

shannot run script.py

"Session already executed"¶

Symptoms:

Error: Session 'xxx' was already executed

Solution: Create a new session for re-execution:

shannot run script.py

Remote Execution Issues¶

SSH Connection Failed¶

Symptoms:

Error: SSH connection failed: Connection refused
Error: SSH connection failed: Permission denied

Solutions:

Test SSH manually:
```
ssh user@host
```

Check SSH key permissions:

chmod 600 ~/.ssh/id_rsa
chmod 700 ~/.ssh

Verify host in known_hosts:

ssh-keygen -R host
ssh user@host  # Accept new key

Check SSH agent:
```
eval $(ssh-agent)
ssh-add ~/.ssh/key
```

Remote Deployment Failed¶

Symptoms:

Error: Failed to deploy to remote

Solutions:

Check remote access:
```
ssh user@host "ls -la /tmp/"
```
Check disk space on remote:
```
ssh user@host "df -h /tmp"
```

Manual deployment check:

ssh user@host "test -x /tmp/shannot-v0.5.1/shannot && echo OK"

Remote Target Not Found¶

Symptoms:

Error: Remote 'xxx' not found in configuration

Solutions:

List configured remotes:
```
shannot setup remote list
```

Add the remote:

shannot setup remote add name user@host

Profile Issues¶

Profile Not Loading¶

Symptoms:

Using default profile (no custom profile found)

Solutions:

Check config location:

ls -la ~/.config/shannot/config.toml
ls -la .shannot/config.toml

View config contents:
```
cat ~/.config/shannot/config.toml
```
Check current profile:
```
shannot status
```

Command Not Auto-Approved¶

Symptoms: Commands that should be auto-approved require manual approval.

Causes: 1. Command not in auto_approve list 2. Using full path instead of base name

Solution: Use base command names in profiles:

{
  "auto_approve": ["cat", "ls", "grep"]
}

Not:

{
  "auto_approve": ["/usr/bin/cat", "/usr/bin/ls"]
}

Command Unexpectedly Blocked¶

Symptoms: Command is blocked even though it's not in always_deny.

Cause: Prefix matching in always_deny.

Example:

{
  "always_deny": ["rm"]  // Blocks ALL rm commands
}

Solution: Be specific:

{
  "always_deny": ["rm -rf /", "rm -rf ~"]
}

TUI Issues¶

TUI Not Rendering Correctly¶

Symptoms: - Garbled display - Missing colors - Cursor positioning issues

Solutions:

Check terminal type:
```
echo $TERM
```
Try a different terminal emulator
Disable colors:
```
shannot run script.py --nocolor
```

Keyboard Input Not Working¶

Symptoms: Arrow keys or vim keys don't work.

Solution: Ensure terminal supports raw mode. Some terminals or SSH configurations may interfere.

MCP Issues¶

MCP Server Not Starting¶

Symptoms: - Claude Desktop can't connect to shannot - "Server not responding" errors

Solutions:

Test MCP server manually:
```
shannot-mcp --verbose
```

Check Claude Desktop config:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Reinstall MCP configuration:
```
shannot setup mcp install
```
Restart Claude Desktop completely

MCP Permission Errors¶

Symptoms: - Operations fail with permission denied - Sandbox can't access files

Solution: Check that the runtime is installed and accessible:

shannot setup runtime
shannot status

Checkpoint and Rollback Issues¶

"Conflict detected" during rollback¶

Symptoms:

Error: Conflict detected - file was modified since execution

Cause: A file was modified after the session was executed, and the current content differs from what Shannot wrote.

Solutions:

Review the conflict:
```
shannot checkpoint show SESSION_ID
```
Force rollback (overwrites current changes):
```
shannot rollback SESSION_ID --force
```
Manually restore the file from the checkpoint blob

"Partial checkpoint" warning¶

Symptoms:

Warning: Partial checkpoint - directory too large to fully checkpoint

Cause: Large directories (>100 files or >50MB) cannot be fully checkpointed.

Impact: These directories cannot be restored via rollback.

Solutions: 1. Accept the limitation for large directories 2. Manually backup large directories before execution 3. Use smaller, more targeted scripts

"No checkpoint" error¶

Symptoms:

Error: Session has no checkpoint

Causes: 1. Session was executed before v0.11.0 2. Checkpoint creation failed 3. Session was created in dry-run only mode

Solutions: 1. Create a new session and execute it 2. Check session details:

shannot checkpoint show SESSION_ID

Checkpoint not created¶

Symptoms: Session executed but no checkpoint is available.

Cause: The session may have been created before the checkpoint feature was added.

Solution: Re-run the script to create a new session with checkpoint support.

Getting Help¶

If you're still stuck:

Run diagnostics:

shannot status
shannot setup runtime --status

Enable debug mode:
```
shannot run script.py --debug
```
Check version:
```
shannot --version
```
Open an issue: https://github.com/corv89/shannot/issues

Include in your issue: - Output of shannot status - Output of shannot --version - Error message and stack trace - Steps to reproduce