---
title: "Troubleshooting"
source: https://docs.autohand.ai/guides/troubleshooting
---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

``` json
{
  "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.

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

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

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

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

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

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

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

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

``` bash
# 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](https://twitter.com/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:

``` bash
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.
```