Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.namastex.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation Issues

​
Command Not Found

Problem: automagik-forge: command not found after global install 
# 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

# Run directly without installing
npx automagik-forge

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

# 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

​
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: 
# 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

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

# Linux (ufw)
sudo ufw status

# Windows
# Check Windows Defender Firewall settings

# 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:
1

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
2

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
3

Clear Cached Tokens

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

# Restart Forge
automagik-forge
4

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 CPU and memory usage
top

# Check disk space
df -h

# Free up space if needed
# Clean up old worktrees

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

# 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