Skip to main content

Troubleshooting

Common issues and solutions when using ANOLISA components.

Diagnostic Tools​

ANOLISA provides built-in diagnostic commands to help identify and resolve problems.

anolisa doctor​

Runs a comprehensive health check across all installed components:

anolisa doctor

Checks include:

  • Component binary availability
  • Configuration file validity
  • Runtime dependencies (FUSE, btrfs, eBPF)
  • Adapter connectivity
  • Permission issues

anolisa bug​

Generates a diagnostic report for filing bug reports:

anolisa bug

This collects system info, component versions, configuration, and recent logs into a single report file.

anolisa logs​

View component logs:

# View logs for a specific component
anolisa logs <component>

# Follow logs in real-time
anolisa logs <component> --follow

# Show last N lines
anolisa logs <component> --tail 50

Common Issues​

Permission Errors​

Symptom: Permission denied when running anolisa install

Cause: Some components require system mode (root privileges).

Solution:

# For system-mode components (agentsight, agent-sec-core)
sudo anolisa install <component>

# For user-mode components, ensure ~/.local/bin is writable
ls -la ~/.local/bin/

Symptom: Permission denied accessing /dev/fuse

Cause: User not in the fuse group or device not available.

Solution:

# Add user to fuse group
sudo usermod -aG fuse $USER

# Verify device exists
ls -la /dev/fuse

Component Installation Failures​

Symptom: anolisa install tokenless fails with network error

Solution:

# Check network connectivity
anolisa doctor --check network

# Retry with verbose output
anolisa install tokenless --verbose

# Alternative: use YUM
sudo yum install tokenless

Symptom: cargo build fails during source compilation

Solution:

# Ensure Rust toolchain is installed
rustup show

# Update to latest stable
rustup update stable

# Check for missing system dependencies
anolisa doctor --check build-deps

Adapter Issues​

Symptom: Tokenless hook not activating in cosh

Solution:

# Verify hook installation
ls ~/.config/cosh/hooks/

# Reinstall the hook
/usr/share/tokenless/scripts/install.sh --cosh

# Check cosh hook config
cat ~/.config/cosh/config.toml | grep -A5 hooks

Symptom: ws-ckpt plugin not detected by OpenClaw

Solution:

# Reinstall the plugin
ws-ckpt plugin install --runtime openclaw

# Verify plugin registration
anolisa status ws-ckpt

# Check OpenClaw plugin directory
ls ~/.config/openclaw/plugins/

ws-ckpt Issues​

Symptom: ws-ckpt checkpoint fails with "not a btrfs filesystem"

Solution:

# Check filesystem type
df -T /path/to/workspace

# ws-ckpt will fall back to rsync if btrfs is unavailable
# Ensure workspace path is correctly configured
ws-ckpt config

Symptom: "workspace path must not be Agent startup directory"

Cause: ws-ckpt workspace is set to the Agent's CWD or a parent directory.

Solution: Change the workspace path to a dedicated project directory:

ws-ckpt config set workspace.path /home/user/projects/my-project

SkillFS Issues​

Symptom: skillfs mount fails with "FUSE not available"

Solution:

# Install FUSE3
sudo yum install fuse3 fuse3-devel

# Load FUSE kernel module
sudo modprobe fuse

# Verify
ls /dev/fuse

AgentSight Issues​

Symptom: AgentSight shows no eBPF data

Cause: Insufficient kernel capabilities or eBPF not supported.

Solution:

# Check kernel version (>= 5.4 recommended)
uname -r

# Verify eBPF support
anolisa doctor --check ebpf

# AgentSight requires system mode
sudo anolisa install agentsight

Getting Help​

If the above steps don't resolve your issue:

  1. Run anolisa bug and attach the report
  2. Check component-specific logs: anolisa logs <component>
  3. File an issue on the ANOLISA GitHub repository