Skip to main content

Troubleshooting

This guide covers common issues you might encounter when using Clawrium and how to resolve them.

SSH Connection Issues​

"Connection refused" Error​

Symptoms:

Testing connection to 192.168.1.100:22 as xclm...
Connection failed: Connection refused

Causes & Solutions:

  1. SSH service not running on host

    # On the target host, check SSH service status
    sudo systemctl status sshd
    # Start if not running
    sudo systemctl start sshd

  2. Wrong port number

    # Specify the correct SSH port
    clm host add 192.168.1.100 --port 2222

  3. Firewall blocking connection

    # On the target host, allow SSH
    sudo ufw allow ssh
    # Or for specific port
    sudo ufw allow 2222/tcp

"Permission denied (publickey)" Error​

Symptoms:

Permission denied (publickey)

Causes & Solutions:

  1. Keypair not initialized

    Run clm host init first to generate the keypair:

    clm host init 192.168.1.100 --user myuser

  2. xclm user not configured

    If automatic setup failed, manually configure the xclm user:

    # Create xclm user
    sudo useradd -m -s /bin/bash xclm

    # Grant passwordless sudo
    echo "xclm ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/xclm
    sudo chmod 440 /etc/sudoers.d/xclm

    # Add public key (from Clawrium's output)
    sudo mkdir -p /home/xclm/.ssh
    sudo chmod 700 /home/xclm/.ssh
    echo '<public-key-from-clm-host-init>' | sudo tee /home/xclm/.ssh/authorized_keys
    sudo chmod 600 /home/xclm/.ssh/authorized_keys
    sudo chown -R xclm:xclm /home/xclm/.ssh

  3. Wrong SSH user

    For clm host add, Clawrium uses xclm by default. If you used a different user during init:

    clm host add 192.168.1.100 --user customuser

Host Key Verification Failed​

Symptoms:

Unknown host key for 192.168.1.100
  Key type: ssh-ed25519
  Fingerprint: SHA256:abc123...

Solution:

This is a security feature. Verify the fingerprint matches the host's actual key:

# On the target host
ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub

If the fingerprints match, accept the key when prompted by Clawrium.

To remove a saved host key (e.g., after host reinstallation):

ssh-keygen -R 192.168.1.100

Host Management Issues​

"Host already exists" Error​

Symptoms:

Error: Host '192.168.1.100' already exists in fleet

Solution:

Remove the existing host entry first:

clm host remove 192.168.1.100
clm host init 192.168.1.100

Or use the alias to differentiate:

clm host add 192.168.1.100 --alias new-name

"Keypair not found" Error​

Symptoms:

Error: No keypair found for '192.168.1.100'. Run 'clm host init' first.

Solution:

Initialize the host first to generate the keypair:

clm host init 192.168.1.100

Hardware Detection Fails​

Symptoms:

Detecting hardware capabilities...
Warning: Could not detect GPU

Solution:

Hardware detection requires certain commands on the host. Ensure the host has:

  • lscpu for CPU info (usually pre-installed)
  • free for memory info (usually pre-installed)
  • nvidia-smi for NVIDIA GPU detection (only if GPU present)

For manual refresh:

clm host status 192.168.1.100 --refresh

Host Reset Issues​

Reset Fails with "User has active processes"​

Symptoms:

Error: Cannot remove user 'zc-work': user is currently logged in

Solution:

Kill active processes before reset:

# On the target host
sudo pkill -u zc-work
sudo pkill -u oc-home

Then retry the reset:

clm host reset 192.168.1.100 --yes

Reset Doesn't Remove Everything​

Symptoms: Some files or users remain after reset.

Solution:

Check what the reset would remove first:

clm host reset 192.168.1.100 --dry-run

The reset only removes:

  • Users with UID >= 1000 (except xclm)
  • *claw systemd services
  • Standard clawrium paths

Manual cleanup may be needed for custom installations.

Configuration Issues​

"Config directory not writable"​

Symptoms:

Error: Cannot write to ~/.config/clawrium/

Solution:

Check and fix permissions:

ls -la ~/.config/clawrium/
chmod 700 ~/.config/clawrium/
chmod 600 ~/.config/clawrium/*.json
chmod 600 ~/.config/clawrium/keys/*/*

Corrupted hosts.json​

Symptoms:

Error: Failed to parse hosts.json

Solution:

Backup and recreate the config:

# Backup existing config
cp ~/.config/clawrium/hosts.json ~/.config/clawrium/hosts.json.bak

# View the corrupted file
cat ~/.config/clawrium/hosts.json

# If unrecoverable, remove and re-add hosts
rm ~/.config/clawrium/hosts.json
clm host add 192.168.1.100  # Re-initialize each host

Debug Logging​

Enable verbose output for troubleshooting:

# Enable Ansible verbose mode
export ANSIBLE_VERBOSITY=3
clm host init 192.168.1.100

Getting Help​

If you can't resolve an issue:

  1. Search existing issues: GitHub Issues
  2. Start a discussion: GitHub Discussions
  3. File a bug report: Include:
    • Clawrium version (clm --version)
    • Full error message
    • Steps to reproduce
    • OS and architecture of both client and target host