Troubleshooting

This guide helps you resolve common issues with SwissArmyHammer. For additional support, check the GitHub Issues.

Quick Diagnostics

Run the doctor command for automated diagnosis:

swissarmyhammer doctor --verbose

Installation Issues

Command Not Found

Problem: swissarmyhammer: command not found

Solutions:

Verify installation:

ls -la ~/.local/bin/swissarmyhammer
# or
ls -la /usr/local/bin/swissarmyhammer

Add to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Reinstall:

curl -sSL https://raw.githubusercontent.com/wballard/swissarmyhammer/main/install.sh | bash

Permission Denied

Problem: Permission denied when running swissarmyhammer

Solutions:

# Make executable
chmod +x $(which swissarmyhammer)

# If installed system-wide, use sudo
sudo chmod +x /usr/local/bin/swissarmyhammer

Installation Script Fails

Problem: Install script errors or hangs

Solutions:

Manual installation:

# Download binary directly
curl -L https://github.com/wballard/swissarmyhammer/releases/latest/download/swissarmyhammer-linux-x64 -o swissarmyhammer
chmod +x swissarmyhammer
sudo mv swissarmyhammer /usr/local/bin/

Build from source:

git clone https://github.com/wballard/swissarmyhammer.git
cd swissarmyhammer
cargo build --release
sudo cp target/release/swissarmyhammer /usr/local/bin/

MCP Server Issues

Server Won’t Start

Problem: swissarmyhammer serve fails to start

Solutions:

Check port availability:

# Default port
lsof -i :8080

# Try different port
swissarmyhammer serve --port 8081

Debug mode:
```
swissarmyhammer serve --debug
```

Check permissions:

# Ensure read access to prompt directories
ls -la ~/.swissarmyhammer/prompts

Claude Code Connection Issues

Problem: SwissArmyHammer doesn’t appear in Claude Code

Solutions:

Verify MCP configuration:
```
claude mcp list
```

Re-add server:

claude mcp remove swissarmyhammer
claude mcp add swissarmyhammer swissarmyhammer serve

Check server is running:

# In another terminal
ps aux | grep swissarmyhammer

Restart Claude Code:
- Close Claude Code completely
- Start Claude Code
- Check MCP servers are connected

MCP Protocol Errors

Problem: Protocol errors in Claude Code logs

Solutions:

Update SwissArmyHammer:

# Check version
swissarmyhammer --version

# Update to latest
curl -sSL https://install.sh | bash

Check logs:

# Enable debug logging
swissarmyhammer serve --debug > debug.log 2>&1

Validate prompt syntax:
```
swissarmyhammer doctor --check prompts
```

Prompt Issues

Prompts Not Loading

Problem: Prompts don’t appear or are outdated

Solutions:

Check directories:

# List prompt directories
ls -la ~/.swissarmyhammer/prompts
ls -la ./prompts

Validate prompts:

swissarmyhammer test <prompt-name>
swissarmyhammer doctor --check prompts --verbose

Force reload:

# Restart server
# Ctrl+C to stop, then:
swissarmyhammer serve

Invalid YAML Front Matter

Problem: YAML parsing errors

Common Issues:

Missing quotes:

# Bad
description: This won't work: because of the colon

# Good
description: "This works: because it's quoted"

Incorrect indentation:

# Bad
arguments:
- name: test
description: Test argument

# Good
arguments:
  - name: test
    description: Test argument

Missing required fields:

# Must have name, title, description
---
name: my-prompt
title: My Prompt
description: What this prompt does
---

Template Rendering Errors

Problem: Liquid template errors

Common Issues:

Undefined variables:

# Error: undefined variable 'foo'
{{ foo }}

# Fix: Check if variable exists
{% if foo %}{{ foo }}{% endif %}

Invalid filter:

# Error: unknown filter
{{ text | invalid_filter }}

# Fix: Use valid filter
{{ text | capitalize }}

Syntax errors:

# Error: unclosed tag
{% if condition %}

# Fix: Close all tags
{% if condition %}...{% endif %}

Duplicate Prompt Names

Problem: Multiple prompts with same name

Solutions:

Check override hierarchy:

swissarmyhammer list --verbose | grep "prompt-name"

Rename conflicts:
- Local prompts override user prompts
- User prompts override built-in prompts
- Rename one to avoid confusion

Performance Issues

Slow Prompt Loading

Problem: Server takes long to start or reload

Solutions:

Disable file watching:
```
swissarmyhammer serve --watch false
```

Limit prompt directories:

swissarmyhammer serve --prompts ./essential-prompts --builtin false

Check directory size:

find ~/.swissarmyhammer/prompts -type f | wc -l

High Memory Usage

Problem: Excessive memory consumption

Solutions:

Monitor usage:
```
top | grep swissarmyhammer
```

Optimize configuration:

# Disable file watching
swissarmyhammer serve --watch false

# Reduce prompt count
# Move unused prompts to archive

System limits:

# Check ulimits
ulimit -a

# Increase if needed
ulimit -n 4096

File System Issues

Permission Errors

Problem: Cannot read/write prompt files

Solutions:

Fix directory permissions:

chmod -R 755 ~/.swissarmyhammer
chmod -R 644 ~/.swissarmyhammer/prompts/*.md

Check ownership:

ls -la ~/.swissarmyhammer/
# Fix if needed
chown -R $USER:$USER ~/.swissarmyhammer

File Watching Not Working

Problem: Changes to prompts not detected

Solutions:

Check file system support:

# macOS
fs_usage | grep swissarmyhammer

# Linux
inotifywait -m ~/.swissarmyhammer/prompts

Increase watch limits (Linux):

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Manual reload:
- Restart the server
- Or disable watching: --watch false

CLI Command Issues

Test Command Fails

Problem: swissarmyhammer test errors

Solutions:

Check prompt exists:

swissarmyhammer list | grep "prompt-name"

Validate arguments:

# Show required arguments
swissarmyhammer test prompt-name --help

Debug mode:

swissarmyhammer test prompt-name --debug

Export/Import Errors

Problem: Cannot export or import prompts

Solutions:

Check file permissions:

# For export
touch test-export.tar.gz

# For import
ls -la import-file.tar.gz

Validate archive:
```
tar -tzf archive.tar.gz
```

Manual export:

tar -czf prompts.tar.gz -C ~/.swissarmyhammer prompts/

Environment-Specific Issues

macOS Issues

Problem: Security warnings or quarantine

Solutions:

# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/swissarmyhammer

# Allow in Security & Privacy settings
# System Preferences > Security & Privacy > General

Linux Issues

Problem: Library dependencies missing

Solutions:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install libssl-dev

# Fedora
sudo dnf install openssl-devel

# Check dependencies
ldd $(which swissarmyhammer)

Windows Issues

Problem: Path or execution issues

Solutions:

Use PowerShell as Administrator

Add to PATH:

$env:Path += ";C:\Program Files\swissarmyhammer"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::User)

Windows Defender:
- Add exclusion for swissarmyhammer.exe
- Check Windows Security logs

Debug Techniques

Enable Verbose Logging

# Server debug mode
swissarmyhammer serve --debug

# Redirect to file
swissarmyhammer serve --debug > debug.log 2>&1

# CLI debug
RUST_LOG=debug swissarmyhammer test prompt-name

Check Configuration

# Run comprehensive checks
swissarmyhammer doctor --verbose

# Check specific areas
swissarmyhammer doctor --check prompts --check mcp

# Auto-fix issues
swissarmyhammer doctor --fix

Trace MCP Communication

# Save MCP messages
swissarmyhammer serve --debug | grep MCP > mcp-trace.log

# Monitor in real-time
swissarmyhammer serve --debug | grep -E "(request|response)"

Getting Help

Documentation

Check this troubleshooting guide first
Read the CLI Reference
Review Configuration options

Community Support

Reporting Issues

When reporting issues, include:

System information:

swissarmyhammer doctor --json > diagnosis.json

Steps to reproduce
Error messages and logs
Expected vs actual behavior

Debug Information Script

Save this as debug-info.sh:

#!/bin/bash
echo "=== SwissArmyHammer Debug Information ==="
echo "Date: $(date)"
echo "Version: $(swissarmyhammer --version)"
echo "OS: $(uname -a)"
echo ""
echo "=== Doctor Report ==="
swissarmyhammer doctor --verbose
echo ""
echo "=== Configuration ==="
cat ~/.swissarmyhammer/config.toml 2>/dev/null || echo "No config file"
echo ""
echo "=== Prompt Directories ==="
ls -la ~/.swissarmyhammer/prompts 2>/dev/null || echo "No user prompts"
ls -la ./prompts 2>/dev/null || echo "No local prompts"
echo ""
echo "=== Process Check ==="
ps aux | grep swissarmyhammer | grep -v grep

Run and save output:

bash debug-info.sh > debug-info.txt

Common Error Messages

“Failed to bind to address”

Port already in use
Try: --port 8081

“Permission denied”

File/directory permissions issue
Try: chmod +x or check ownership

“YAML parse error”

Invalid YAML syntax in prompt
Check indentation and special characters

“Template compilation failed”

Liquid syntax error
Check tags are closed and filters exist

“Prompt not found”

Prompt name doesn’t exist
Check: swissarmyhammer list

“Connection refused”

MCP server not running
Start server: swissarmyhammer serve

Prevention Tips

Regular maintenance:

# Weekly health check
swissarmyhammer doctor

# Update regularly
swissarmyhammer --version

Backup prompts:

# Regular backups
swissarmyhammer export ~/.swissarmyhammer/backups/prompts-$(date +%Y%m%d).tar.gz

Test changes:

# Before committing
swissarmyhammer test new-prompt
swissarmyhammer doctor --check prompts

Monitor logs:

# Keep logs for debugging
swissarmyhammer serve --debug > server.log 2>&1 &

Keyboard shortcuts

SwissArmyHammer Documentation