Troubleshooting

Common issues and their solutions.

Installation Issues

”ah: command not found”

The ah binary isn’t in your PATH.

Solution:


# Check if installed
which ah
 
# If using Nix, ensure profile is in PATH
echo $PATH | grep -q nix && echo "Nix in PATH" || echo "Add Nix to PATH"
 
# Try running directly
nix run github:blocksense-network/agent-harbor -- --help

Nix Installation Fails

Solution:


# Ensure Nix flakes are enabled
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
 
# Restart Nix daemon (if using multi-user)
sudo systemctl restart nix-daemon
 
# Try again
nix profile install github:blocksense-network/agent-harbor

Agent Issues

”Credentials not found for claude”

Agent credentials aren’t configured.

Solution:


# Check credential status
ah credentials list
 
# Add credentials
ah credentials add claude
 
# Verify
ah credentials verify claude

Agent Enters Onboarding Flow

The agent can’t find its credentials in the sandbox.

Solution:


# Run health check to see credential status
ah health --check-agent-credentials debug
 
# Ensure credentials are properly set up outside sandbox first
claude --version  # Should work without onboarding

“Agent binary not found”

The agent CLI isn’t installed or not in PATH.

Solution:


# Check if agent is available
which claude  # For Claude
which codex   # For Codex
 
# Install the agent CLI
npm install -g @anthropic-ai/claude-code  # Claude
npm install -g @openai/codex              # Codex

Sandbox Issues

”Permission denied” Errors

The sandbox is blocking access to a required path.

Solution:


# Check what's being blocked
ah health
 
# Add path to writable list in config
# .agents/config.toml
[sandbox.writable_paths]
paths = ["~/.cache/pip", "node_modules"]
 
# Or disable sandbox for troubleshooting
ah agent start --sandbox disabled --prompt "Debug task"

Network Requests Failing in Sandbox

Network is disabled by default in sandbox mode.

Solution:


# Enable network access
ah agent start --agent claude --sandbox local --allow-network true --prompt "Install dependencies"

Sandbox Not Available on macOS

System Integrity Protection may be blocking sandbox features.

Solution:


# Check SIP status
csrutil status
 
# Some sandbox features require specific entitlements
# Use less restrictive sandbox or VM-based isolation
ah agent start --agent claude --sandbox vm --prompt "Task"

Filesystem Snapshot Issues

”ZFS/Btrfs not detected”

You’re on a filesystem without native CoW support.

Solution:


# Check what's available
ah health --json | jq '.fs_provider'
 
# Use AgentFS or Git fallback
ah agent start --agent claude --fs-snapshots agentfs --prompt "Task"
ah agent start --agent claude --fs-snapshots git --prompt "Task"

AgentFS Mount Fails

AgentFS daemon may not be running or lacks permissions.

Solution:


# Check AgentFS status
ah health
 
# On Linux, ensure FUSE is available
modprobe fuse
ls /dev/fuse
 
# Check permissions
groups | grep -q fuse && echo "In fuse group" || sudo usermod -aG fuse $USER

Snapshot Creation Takes Too Long

You might be using eager materialization with a large workspace.

Solution:


# Use lazy mode for faster snapshots
# .agents/config.toml
overlay-materialization = "lazy"

Or:


ah agent start --overlay-materialization lazy --prompt "Task"

TUI Issues

”No multiplexer detected”

Agent Harbor can’t find a terminal multiplexer.

Solution:


# Install a multiplexer
# tmux (recommended)
brew install tmux    # macOS
apt install tmux     # Debian/Ubuntu
 
# Or specify one
ah tui --multiplexer tmux

TUI Not Rendering Correctly

Terminal doesn’t support required features.

Solution:


# Use ASCII mode
ah config set tui-font-style ascii
 
# Or ensure your terminal supports Unicode
echo "╭─────╮"  # Should render as box corners

Keyboard Shortcuts Not Working

Multiplexer may be capturing keys.

Solution:


# Check multiplexer prefix key conflicts
# For tmux, default prefix is Ctrl+B
 
# In tmux.conf, you can change prefix:
# set -g prefix C-a

Recording Issues

Recording File Too Large

High-volume output is being captured.

Solution:


# Use headless mode for CI (smaller overhead)
ah agent record --headless -o session.ahr -- ah agent start ...
 
# Consider shorter sessions and checkpoint more often

Replay Shows Garbled Output

Terminal size mismatch or encoding issues.

Solution:


# Record with explicit terminal size
ah agent record --cols 120 --rows 40 -o session.ahr -- ah agent start ...
 
# Ensure terminal encoding is UTF-8
echo $LANG  # Should contain UTF-8

Configuration Issues

Config Not Being Applied

Wrong precedence or file location.

Solution:


# Check where values come from
ah config explain <key>
 
# Show all config with sources
ah config show --json
 
# Verify file locations
ls -la ~/.config/agent-harbor/
ls -la .agents/

Environment Variables Ignored

Variables may be formatted incorrectly.

Solution:


# Correct format: AH_ prefix, underscores, uppercase
export AH_DEFAULT_AGENT="claude"      # Correct
export AH-DEFAULT-AGENT="claude"      # Wrong
export ah_default_agent="claude"      # Wrong
 
# Verify
env | grep AH_

Getting Help

Run Health Check


ah health
ah health --json  # For detailed output

Enable Debug Logging


export AH_LOG_LEVEL=debug
ah agent start --agent claude --prompt "Task"

Check Logs


# Default log location
cat ~/.local/share/agent-harbor/logs/ah.log

Report Issues

Include the following when reporting issues:


# System info
uname -a
ah --version
 
# Health check output
ah health --json
 
# Relevant logs (redact sensitive info)