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
```
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' first.

Solution:

# Install runtime
shannot setup

# Force reinstall
shannot setup --force

# Check status
shannot setup --status

"lib-python not found"¶

Symptoms:

Error: lib-python directory not found at expected location

Solution:

# Reinstall runtime
shannot setup --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 remote list
```
Add the remote:
```
shannot remote add name user@host
```

Profile Issues¶

Profile Not Loading¶

Symptoms:

Using default profile (no custom profile found)

Solutions:

Check profile location:

ls -la ~/.config/shannot/profile.json
ls -la .shannot/profile.json

Verify JSON syntax:

python3 -m json.tool ~/.config/shannot/profile.json

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 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
shannot status

Getting Help¶

If you're still stuck:

Run diagnostics:
```
shannot status
shannot setup --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