Guides

Troubleshooting

Practical solutions for the most common issues you will run into with Autohand Code. Each problem lists the symptom, the cause, and the fix with a working example.

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.

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

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

# Configure Autohand to use your proxy
autohand config set network.proxy "http://proxy.company.com:8080"

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.

# Check which key is configured
autohand config get providers.openai.apiKey
# Shows: sk-...****  (masked)

# Set a new key
autohand config set providers.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.retryMaxAttempts 5
autohand config set network.retryBaseDelayMs 2000

# For auto-mode, increase the delay between iterations
autohand config set autoMode.iterationDelayMs 3000

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 (default: 120 seconds)
autohand config set network.timeoutMs 180000

# For local models that are slow on first load
autohand config set network.timeoutMs 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

# Configure proxy in Autohand
autohand config set network.proxy "http://proxy.company.com:8080"
autohand config set network.noProxy "localhost,127.0.0.1,.internal.company.com"

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.

# List available models for your configured provider
autohand models list

# 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

# If context is large, compact it
/compact

# 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: reduce context and use quantized models
autohand config set providers.llamacpp.contextSize 4096
autohand config set providers.llamacpp.model "/path/to/model-Q4_K_M.gguf"

# 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 file writes in the current project
/permissions allow write_file --scope project

# Allow shell commands matching a pattern
/permissions allow shell_command --pattern "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 non-standard directory, use --workspace
autohand --workspace /path/to/safe/directory

# Override safety checks (not recommended)
autohand --allow-unsafe-workspace

Resetting permissions

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

# Reset all permission rules to defaults
/permissions reset

# Reset only project-level permissions
/permissions reset --scope project

# View the raw permissions file
cat ~/.autohand/permissions.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 list

# 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

# Compact the conversation to free space
/compact

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

# Prevent this in the future by enabling auto-compaction
autohand config set context.autoCompact true
autohand config set context.compactThreshold 0.8

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."

# Compact to clear old context
/compact

# Switch to a stronger model for hard problems
/model claude-sonnet-4

# 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.

# Check the current limit
autohand config get autoMode.maxIterations

# Increase it if the task genuinely needs more iterations
autohand config set autoMode.maxIterations 50

# Review what the agent did so far
/history

# Resume auto-mode to continue from where it stopped
/auto continue

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
/auto "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
/auto --max-iterations 10 "Add input validation to the signup form"

Cost limit reached

Symptom: Session cost limit reached: $X.XX.

Cause: You configured a per-session spending limit and the session hit it. This is a safety feature to prevent unexpected bills.

# Check current cost limit
autohand config get costLimit.perSession

# Increase the limit
autohand config set costLimit.perSession 10.00

# Check what this session has spent so far
/cost

# Remove the limit entirely (be careful)
autohand config set costLimit.perSession 0

Checkpoint recovery

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

# List available checkpoints
/checkpoints

# Restore to a specific checkpoint
/checkpoint restore cp-abc123

# Checkpoints are git commits, so you can also use git directly
git log --oneline | grep "autohand-checkpoint"
git checkout autohand-checkpoint-1709560200

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

# Compact to reduce context size
/compact

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

# Check if your system prompt is very large
wc -c ~/.autohand/CLAUDE.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 usage for the current session
/cost

# Enable context compaction to keep usage lower
autohand config set context.autoCompact true
autohand config set context.compactThreshold 0.7

# 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: You run /compact 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 --detailed

# 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
/clear

# Reduce the system prompt size
autohand config set systemPrompt.maxLength 4000

Performance tips summary: Use /compact regularly in long sessions. 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.