Troubleshooting - Autohand Docs

Installation issues

Node.js version mismatch

Symptom: You see an error like Unsupported engine or SyntaxError: Unexpected token during install.

Cause: Autohand requires Node.js 20 or later. Older versions do not support the JavaScript features Autohand uses.

# Check your current Node version
node --version

# If it shows v18 or lower, upgrade
# Using nvm (recommended)
nvm install 22
nvm use 22

# Using Homebrew on macOS
brew install node@22

# Verify the upgrade worked
node --version
# v22.x.x

Permission errors on install

Symptom: You see EACCES: permission denied when running npm install -g autohand-cli.

Cause: Your global npm directory is owned by root, which means regular users cannot write to it.

# Fix: Configure npm to use a user-level directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PATH="$HOME/.npm-global/bin:$PATH"

# Reload your shell and install again
source ~/.zshrc
npm install -g autohand-cli

Do not use sudo npm install -g. It creates files owned by root that cause problems later.

Binary not found after install

Symptom: Install succeeds but running autohand shows command not found.

Cause: The npm global bin directory is not in your PATH.

# Find where npm installs global binaries
npm bin -g

# Add that path to your shell profile
# For zsh (~/.zshrc):
export PATH="$(npm bin -g):$PATH"

# For bash (~/.bashrc):
export PATH="$(npm bin -g):$PATH"

# Reload and verify
source ~/.zshrc
which autohand
# /Users/you/.npm-global/bin/autohand

PATH not configured on Windows

Symptom: autohand is not recognized in PowerShell or CMD.

Cause: The npm global path was not added to the system PATH during Node.js installation.

# Check where npm installs globals
npm bin -g

# Add to your PowerShell profile
# Open $PROFILE in an editor:
notepad $PROFILE

# Add this line (replace with your actual path):
$env:PATH += ";C:\Users\you\AppData\Roaming\npm"

# Restart PowerShell and test
autohand --version

Connection and API errors

Provider connection refused

Symptom: ECONNREFUSED or connect ETIMEDOUT when starting a session.

Cause: The model provider's API endpoint is not reachable from your network. This can be a firewall rule, a VPN issue, or the provider being down.

# Test connectivity to the provider
curl -I https://api.openai.com/v1/models
curl -I https://api.anthropic.com/v1/messages

# If those fail, check your proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Autohand has no proxy setting in its config file.
# If the provider is only reachable through a proxy, ask your network team
# to allow the provider endpoints for the machine that runs Autohand.

API key invalid or expired

Symptom: 401 Unauthorized or Invalid API key error.

Cause: The API key in your configuration is wrong, expired, or belongs to a deactivated account.

# Review provider settings in the settings menu
autohand config

# Set a new key
autohand config set openai.apiKey "sk-your-new-key"

# Or set it via environment variable
export OPENAI_API_KEY="sk-your-new-key"

# Verify the key works
autohand doctor

Rate limiting

Symptom: 429 Too Many Requests or Rate limit exceeded.

Cause: You have sent too many requests to the provider within their rate window. This is common with free-tier API keys or during heavy auto-mode usage.

# Autohand automatically retries with backoff, but you can tune it
autohand config set network.maxRetries 5
autohand config set network.retryDelay 2000

# For auto-mode, lower the number of iterations
autohand --auto-mode "Your task" --max-iterations 10

If rate limiting happens often, consider upgrading your provider plan or switching to a provider with higher limits.

Timeout errors

Symptom: Request timeout or the session hangs waiting for a response.

Cause: The model is taking too long to respond. This happens with large prompts, complex tasks, or when the provider is under heavy load.

# Increase the request timeout in milliseconds (default: 30000)
autohand config set network.timeout 180000

# For local models that are slow on first load
autohand config set network.timeout 300000

Network proxy issues

Symptom: Works at home but fails at work, or UNABLE_TO_GET_ISSUER_CERT_LOCALLY errors.

Cause: Corporate proxies often use custom TLS certificates that Node.js does not trust by default.

# Point Node.js to your corporate CA bundle
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem"

# Or disable strict TLS (not recommended for production)
export NODE_TLS_REJECT_UNAUTHORIZED=0

Model issues

Model not available

Symptom: Model 'xyz' is not available or model_not_found error.

Cause: The model name is misspelled, not supported by your provider, or your account does not have access to it.

# Refresh the model catalog
autohand update --models

# Switch to a model you have access to
/model gpt-4o

# Check which model is currently selected
/model

Model responding slowly

Symptom: Long delays between your message and the model's response.

Cause: Large context windows, complex system prompts, or provider congestion. Local models may also be slow if your hardware is not fast enough.

# Check your context window usage
/status

# Context compaction is on by default; /cc toggles it
/cc

# Switch to a faster model for simple tasks
/model gpt-4o-mini

# For local models, check GPU usage
nvidia-smi  # NVIDIA GPUs
# or
system_profiler SPDisplaysDataType  # macOS GPU info

Out of memory with local models

Symptom: Ollama, llama.cpp, or MLX crashes with out of memory or the system becomes unresponsive.

Cause: The model is too large for your available RAM or VRAM. A 70B parameter model needs roughly 40 GB of memory at Q4 quantization.

# For Ollama: switch to a smaller model
ollama run llama3.2:8b  # Instead of llama3.1:70b

# For llama.cpp: start the server with a smaller context and a quantized model
llama-server -m /path/to/model-Q4_K_M.gguf -c 4096
autohand config set llamacpp.model "model-Q4_K_M"

# For MLX on Apple Silicon: check unified memory
sysctl hw.memsize
# A 32 GB Mac can comfortably run 8B-13B models
# Use Q4 quantization for larger models

Wrong model selected

Symptom: Responses feel off or the model does not follow instructions well.

Cause: A different model than expected is active. This can happen if an environment variable overrides your config, or if you switched models in a previous session.

# Check what model is active right now
/model

# Check for environment variable overrides
echo $AUTOHAND_MODEL
echo $AUTOHAND_PROVIDER

# Reset to your configured default
/model default

# Or set it explicitly
/model claude-sonnet-4

Permission problems

Tool blocked by permissions

Symptom: The agent says Permission denied for tool: write_file or asks for approval on every action.

Cause: Your permission configuration is restrictive. By default, Autohand asks before writing files or running commands.

# Check current permission settings
/permissions

# Allow commands that match a pattern in ~/.autohand/config.json:
#   "permissions": { "allowList": ["run_command:npm test*"] }

# Or use yolo mode to skip all prompts (use carefully)
autohand --yolo

File access denied

Symptom: EACCES errors when the agent tries to read or write files.

Cause: The file or directory has filesystem permissions that prevent your user from accessing it. This is separate from Autohand's permission system.

# Check file permissions
ls -la /path/to/file

# Fix ownership if needed
sudo chown -R $(whoami) /path/to/directory

# Fix permissions
chmod 644 /path/to/file      # Read/write for owner, read for others
chmod 755 /path/to/directory  # Execute for directories

Workspace safety check failures

Symptom: Workspace safety check failed when starting a session in a directory.

Cause: Autohand checks that the workspace is safe to operate in. It will refuse to run in sensitive directories like /, /etc, ~, or directories containing credential files at the root level.

# Start Autohand in your project directory instead
cd ~/projects/my-app
autohand

# If you need to work in a different directory, use --path
autohand --path /path/to/safe/directory

Resetting permissions

Symptom: Permissions got into a confusing state and you want to start fresh.

# Review the effective permission settings
/permissions

# Project decisions are saved here; remove entries you no longer want
cat .autohand/settings.local.json

# User-level rules live under "permissions" in your config
cat ~/.autohand/config.json

Session issues

Session will not resume

Symptom: /resume shows No session found or loads a blank session.

Cause: The session file may have been corrupted, deleted, or the session was too old and got cleaned up.

# List recent sessions
autohand sessions

# Resume a specific session by ID
autohand resume abc123

# If session files are corrupted, clear them
rm -rf ~/.autohand/sessions/corrupted-session-id

# Start a fresh session
autohand

Context too large

Symptom: Context length exceeded or the model starts giving confused, repetitive answers.

Cause: The conversation has grown beyond the model's context window. This happens naturally in long sessions, especially when many files have been read.

# Check current context usage
/status

# If compaction was turned off, turn it back on
/cc

# If that is not enough, start a fresh session
# with the context you need
/new

# Context compaction is on by default; do not start with --no-cc

Conversation stuck

Symptom: The agent repeats itself, goes in circles, or stops making progress.

Cause: The model may be confused by contradictory instructions in the context, or the task is outside its abilities. This also happens when the context is nearly full.

# Try rephrasing your request more specifically
# Instead of "fix the tests", try:
# "The test in src/auth.test.ts line 45 fails because
#  the mock does not return a token. Add a token to the mock."

# Start a fresh session to clear old context
/new

# Open the model picker and choose a stronger model for hard problems
/model

# As a last resort, start fresh
/clear

Git and worktree problems

Worktree creation fails

Symptom: fatal: 'branch-name' is already checked out or Preparing worktree (new branch) failed.

Cause: Git does not allow the same branch to be checked out in two worktrees simultaneously. The branch you are trying to use is already active somewhere else.

# See all existing worktrees
git worktree list

# Remove a stale worktree that is no longer needed
git worktree remove /path/to/old-worktree

# Create the worktree with a new branch name
/worktree create feature/my-task-v2

# If the old worktree directory was deleted manually, prune it
git worktree prune

Merge conflicts in auto-mode

Symptom: Auto-mode stops because of merge conflicts when trying to commit or merge.

Cause: The base branch changed while auto-mode was working. The agent's changes conflict with recent commits from other developers.

# Let the agent resolve conflicts
# Just describe what you need:
# "Resolve the merge conflicts in src/api.ts. Keep our
#  new validation logic but accept their updated imports."

# Or resolve manually
git status                    # See conflicted files
git diff                      # See the conflicts
# Edit files to resolve
git add .
git commit -m "resolve merge conflicts"

Stale worktrees

Symptom: git worktree list shows worktrees that no longer exist on disk.

Cause: A worktree directory was deleted manually (with rm -rf) instead of using git worktree remove.

# Clean up all stale worktree references
git worktree prune

# Verify they are gone
git worktree list

Branch cleanup

Symptom: You have dozens of leftover branches from auto-mode and worktree sessions.

# List branches created by Autohand (they follow a naming pattern)
git branch | grep "autohand/"

# Delete merged branches
git branch --merged main | grep "autohand/" | xargs git branch -d

# Force delete unmerged branches you no longer need
git branch | grep "autohand/" | xargs git branch -D

MCP server issues

Server will not connect

Symptom: Failed to connect to MCP server or Connection refused when the session starts.

Cause: The MCP server process failed to start, crashed immediately, or is not listening on the expected address.

# Check if the MCP server process is running
ps aux | grep mcp

# For stdio-based servers, test the command manually
npx @modelcontextprotocol/server-filesystem /tmp

# For HTTP-based servers, verify the endpoint
curl http://localhost:3100/health

# Check Autohand's MCP configuration
cat ~/.autohand/config.json | jq '.mcpServers'

Tools not discovered

Symptom: The MCP server connects but no tools show up in /tools.

Cause: The server's tool listing endpoint is returning an empty array, or the server needs time to initialize its tool catalog.

# Refresh the tool list
/tools refresh

# Check MCP server logs for errors
AUTOHAND_MCP_DEBUG=true autohand

# Verify the server exposes tools correctly
# For stdio servers, test with a direct JSON-RPC call:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx your-mcp-server

Timeout on startup

Symptom: MCP server startup timed out after waiting 30 seconds.

Cause: The server takes longer than the default timeout to initialize. This is common with servers that download data or build indexes at startup.

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-mcp-server"],
      "startupTimeoutMs": 60000
    }
  }
}

Debugging stdio vs HTTP

Symptom: You are not sure whether the problem is with the server or the connection method.

# Test a stdio server directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' \
  | npx your-mcp-server

# Test an HTTP server
curl -X POST http://localhost:3100/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}'

# Enable full MCP protocol logging
AUTOHAND_MCP_DEBUG=verbose autohand

Auto-mode problems

Circuit breaker triggered

Symptom: Circuit breaker: auto-mode stopped after N iterations.

Cause: The agent reached the maximum iteration count without completing the task. The circuit breaker exists to prevent runaway loops.

# Increase the limit if the task genuinely needs more iterations
autohand config set automode.maxIterations 50

# Or set it for one run
autohand --auto-mode "Your task" --max-iterations 50

# Review what the agent did so far
/history

# Resume a paused loop
/automode resume

Stuck in loops

Symptom: The agent keeps doing the same thing over and over, making no progress.

Cause: The task description is too vague, the acceptance criteria are unclear, or the agent is trying to fix something it cannot fix with its available tools.

# Stop auto-mode immediately
# Press Ctrl+C or Esc

# Give more specific instructions
/automode "Fix the failing test in src/auth.test.ts.
The test expects a 200 status but gets 401.
The auth middleware needs to skip validation
for the /health endpoint."

# Set a lower iteration limit for focused tasks
/automode "Add input validation to the signup form" --max-iterations 10

Cost limit reached

Symptom: Auto-mode stops with a cost limit reason.

Cause: Auto-mode has a spending limit (default: $10) and the loop reached it. This is a safety feature to prevent unexpected bills.

# Increase the default auto-mode limit
autohand config set automode.maxCost 20

# Or set it for one run
autohand --auto-mode "Your task" --max-cost 20

# Check token activity
/usage

# For any run, cap requests, tokens, or time
autohand -p "Your task" --max-requests 50 --max-tokens 500000 --max-duration 1800

Checkpoint recovery

Symptom: Auto-mode created a checkpoint but you want to go back to it.

# Revert the last agent file change and conversation turn
/undo

# Auto-mode checkpoints are git commits, so you can use git directly
git log --oneline
git checkout <checkpoint-commit>

Performance

Slow responses

Symptom: Every response takes 10+ seconds, even for simple questions.

Cause: Large context, slow provider, or the system prompt is too long.

# Check what is using your context
/status

# Start a fresh session if the context is large
/new

# Switch to a faster model for quick tasks
/model gpt-4o-mini

# Check if your project instructions are very large
wc -c AGENTS.md
# If it is over 10 KB, consider trimming it

High token usage

Symptom: Sessions consume more tokens than expected and costs are higher than normal.

Cause: Reading large files, having verbose AGENTS.md files, or the agent exploring too many files during a task.

# Check token activity
/usage

# Keep context compaction on (it is on by default)
/cc

# Be specific about which files to read
# Instead of "look at the src directory",
# say "read src/auth/middleware.ts"

Context compaction not working

Symptom: Compaction runs but the context usage barely changes.

Cause: Most of the context is pinned content (system prompt, AGENTS.md, recently read files). Compaction can only shrink the conversation history, not pinned content.

# See what is consuming context
/status

# If AGENTS.md is large, trim it
# Keep only the most relevant instructions

# If many files were read, start a fresh session
# and read only what you need
/new

# Replace or shorten the system prompt for one run
autohand --sys-prompt ./short-prompt.md

Performance tips summary: Start a fresh session with /new when a long session slows down. Switch to faster models for simple tasks. Be specific about which files you need instead of asking the agent to explore. Keep your AGENTS.md under 5 KB.

Getting help

If the solutions on this page do not fix your issue, here is how to get more support.

The /feedback command

The fastest way to report a bug is the built-in feedback command. It automatically includes relevant context (with your permission) so the team can diagnose the problem quickly.

# Report a bug from inside a session
/feedback

# Include your session transcript for full context
# The command will ask before sending anything

GitHub issues

For bugs that need discussion or affect other users, open an issue on the Autohand GitHub repository. Include:

Your Autohand version (autohand --version)
Your operating system and Node.js version
The full error message or unexpected behavior
Steps to reproduce the issue

Community channels

Discord - Join the Autohand community for real-time help from other users and maintainers
GitHub Discussions - Ask questions, share tips, and discuss workflows
Twitter/X - Follow @autohandai for announcements and tips

Diagnostic command

The autohand doctor command runs a full health check and gives you a report you can share with support:

autohand doctor

# Output:
# Autohand v2.4.1
# Node.js v22.1.0
# OS: macOS 15.3 (arm64)
# Shell: /bin/zsh
#
# Providers:
#   openai: connected (gpt-4o available)
#   anthropic: connected (claude-sonnet-4 available)
#   ollama: not configured
#
# MCP Servers:
#   filesystem: running (3 tools)
#   brave-search: running (1 tool)
#
# Permissions: default (ask mode)
# Sync: enabled, last sync 2m ago
# Disk usage: 45 MB in ~/.autohand/
#
# No issues found.