Common Issues

Installation Issues

Command Not Found

Problem: automagik-forge: command not found after global install

Solution 1: Check NPM Global Path

# Find NPM global bin directory
npm config get prefix

# Add to PATH (Linux/macOS)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh users
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
which automagik-forge

Solution 2: Use NPX

# Run directly without installing
npx automagik-forge

# Create alias for convenience
echo 'alias forge="npx automagik-forge"' >> ~/.bashrc

Solution 3: Reinstall Globally

# Remove old installation
npm uninstall -g @automagik/forge

# Clear npm cache
npm cache clean --force

# Reinstall
npm install -g @automagik/forge

# Verify
automagik-forge --version

Unsupported Platform

Problem: ❌ Unsupported platform: linux-arm32 Supported Platforms:

Linux x64
Linux ARM64
macOS x64 (Intel)
macOS ARM64 (Apple Silicon)
Windows x64
Windows ARM64

Solution:

# Build from source for unsupported platforms
git clone https://github.com/namastexlabs/automagik-forge.git
cd automagik-forge
./local-build.sh

# This requires:
# - Rust 1.83+
# - Node.js 18+
# - pnpm 8+

Permission Denied

Problem: EACCES: permission denied during installation

macOS/Linux (Recommended)
Quick Fix (Not Recommended)

Fix NPM permissions (don’t use sudo):

# Create directory for global packages
mkdir ~/.npm-global

# Configure npm to use new directory
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Now install without sudo
npm install -g @automagik/forge

# Use sudo (not ideal, but works)
sudo npm install -g @automagik/forge

# You may need sudo to run it
sudo automagik-forge

Server Issues

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::3000 Solution:

# Find process using the port
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Kill the process
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

# Or use different port
automagik-forge --port 8080 --backend-port 5001

Backend Not Responding

Problem: Frontend loads but API requests fail Symptoms:

Empty task board
“Failed to fetch” errors
Network errors in console

Solutions:

Check Backend Port

# Verify backend is running
curl http://localhost:5000/api/projects

# If it fails, check the port
# Look for "Backend server listening on: http://127.0.0.1:XXXX" in logs

# Update frontend proxy if needed
# Frontend auto-detects backend port from environment

Check Firewall

# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --list

# Linux (ufw)
sudo ufw status

# Windows
# Check Windows Defender Firewall settings

Restart Forge

# Stop Forge (Ctrl+C)

# Clear any stale processes
pkill -f automagik-forge

# Restart
automagik-forge

Database Locked

Problem: database is locked errors Solution:

# Stop Forge
# Ctrl+C or pkill -f automagik-forge

# Check for lock file
ls -la .forge/

# Remove lock if exists
rm .forge/db.sqlite-shm
rm .forge/db.sqlite-wal

# Restart Forge
automagik-forge

GitHub Integration Issues

OAuth Authentication Failed

Problem: GitHub authentication fails or redirects to error page Solutions:

Verify OAuth App Settings

Go to: https://github.com/settings/developersCheck your OAuth app:

Homepage URL: http://localhost:3000
Callback URL: http://localhost:3000/auth/callback

Set Environment Variable

# Set GitHub Client ID
export GITHUB_CLIENT_ID=your_client_id_here

# Or add to .env file
echo "GITHUB_CLIENT_ID=your_client_id" >> .env

Clear Cached Tokens

# Remove cached GitHub token
rm .forge/github-token.enc

# Restart Forge
automagik-forge

Re-authenticate

Open Forge UI
Go to Settings → GitHub
Click “Connect GitHub”
Complete OAuth flow

Repository Not Found

Problem: “Repository not found” after GitHub authentication Solution:

# Verify repository access
gh repo view owner/repo

# Check if repo is private
# Ensure OAuth app has correct permissions

# Re-select repository in Forge UI
# Settings → GitHub → Select Repository

Executor/AI Agent Issues

API Key Not Working

Problem: Tasks fail with “Invalid API key” or “Unauthorized” Solution:

# Verify API key is set
echo $ANTHROPIC_API_KEY  # For Claude
echo $GOOGLE_AI_API_KEY  # For Gemini
echo $OPENAI_API_KEY     # For OpenAI

# Test API key directly
curl -H "x-api-key: $ANTHROPIC_API_KEY" \
  https://api.anthropic.com/v1/messages

# Set if missing
export ANTHROPIC_API_KEY=sk-ant-...

# Or add to .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

# Restart Forge
automagik-forge

Executor Timeout

Problem: Tasks fail with timeout errors Solution:

// Edit .forge/config.json
{
  "executors": {
    "claude-code": {
      // Increase timeout (milliseconds)
      "timeout": 600000  // 10 minutes instead of 5
    }
  }
}

Cursor CLI Not Found

Problem: Cursor CLI executor fails with “command not found” Solution:

# Find Cursor CLI path
which cursor

# Update config with correct path
{
  "executors": {
    "cursor-cli": {
      "cli_path": "/usr/local/bin/cursor",  // or wherever it's installed
      "args": ["--headless"]
    }
  }
}

Performance Issues

Slow Task Execution

Problem: Tasks take very long to complete Solutions:

Check System Resources

# Check CPU and memory usage
top

# Check disk space
df -h

# Free up space if needed
# Clean up old worktrees

Reduce Concurrent Tasks

// Edit .forge/config.json
{
  "worktrees": {
    "max_concurrent": 3  // Reduce from 5
  }
}

Use Faster Executors

# Gemini is typically faster than Claude for simple tasks
# Try different executors for comparison

High Memory Usage

Problem: Forge consuming excessive memory Solution:

# Check memory usage
ps aux | grep forge

# Clean up worktrees
# Via UI: Settings → Cleanup

# Or manually
rm -rf .forge/worktrees/*

# Restart Forge
automagik-forge

UI/Display Issues

Blank Screen

Problem: Forge UI shows blank white screen Solutions:

# Clear browser cache
# Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows/Linux)

# Check browser console for errors
# F12 → Console tab

# Try different browser
# Chrome, Firefox, Safari, Edge

# Verify frontend is running
curl http://localhost:3000

Real-time Updates Not Working

Problem: Task logs don’t stream, UI doesn’t update Solution:

# Check if Server-Sent Events (SSE) are blocked
# Some corporate proxies block SSE

# Verify connection
curl http://localhost:5000/api/events/processes/{id}/logs

# Try different network
# Disable VPN/proxy temporarily

Data Issues

Lost Tasks After Restart

Problem: Tasks disappeared after closing Forge Solution:

# Check database file exists
ls -la .forge/db.sqlite

# Verify database integrity
sqlite3 .forge/db.sqlite "PRAGMA integrity_check;"

# Restore from backup if available
cp .forge/db.backup.sqlite .forge/db.sqlite

Cannot Delete Task

Problem: Task won’t delete, keeps reappearing Solution:

# Force delete via API
curl -X DELETE http://localhost:5000/api/tasks/{task-id}

# Or delete via database
sqlite3 .forge/db.sqlite "DELETE FROM tasks WHERE id='task-id';"

# Restart Forge

Next Steps

Git Worktree Errors

Solutions for git worktree issues

API Errors

Troubleshoot API connection problems

FAQ

Frequently asked questions

Discord Community

Get help from the community

Getting Started

Learn

Configuration

Reference

Troubleshooting

Installation Issues

Command Not Found

Unsupported Platform

Permission Denied

Server Issues

Port Already in Use

Backend Not Responding

Database Locked

GitHub Integration Issues

OAuth Authentication Failed

Repository Not Found

Executor/AI Agent Issues

API Key Not Working

Executor Timeout

Cursor CLI Not Found

Performance Issues

Slow Task Execution

High Memory Usage

UI/Display Issues

Blank Screen

Real-time Updates Not Working

Data Issues

Lost Tasks After Restart

Cannot Delete Task

Next Steps

Git Worktree Errors

API Errors

FAQ

Discord Community

​Installation Issues

​Command Not Found

​Unsupported Platform

​Permission Denied

​Server Issues

​Port Already in Use

​Backend Not Responding

​Database Locked

​GitHub Integration Issues

​OAuth Authentication Failed

​Repository Not Found

​Executor/AI Agent Issues

​API Key Not Working

​Executor Timeout

​Cursor CLI Not Found

​Performance Issues

​Slow Task Execution

​High Memory Usage

​UI/Display Issues

​Blank Screen

​Real-time Updates Not Working

​Data Issues

​Lost Tasks After Restart

​Cannot Delete Task

​Next Steps

Git Worktree Errors

API Errors

FAQ

Discord Community

Installation Issues

Command Not Found

Unsupported Platform

Permission Denied

Server Issues

Port Already in Use

Backend Not Responding

Database Locked

GitHub Integration Issues

OAuth Authentication Failed

Repository Not Found

Executor/AI Agent Issues

API Key Not Working

Executor Timeout

Cursor CLI Not Found

Performance Issues

Slow Task Execution

High Memory Usage

UI/Display Issues

Blank Screen

Real-time Updates Not Working

Data Issues

Lost Tasks After Restart

Cannot Delete Task

Next Steps