ihompadmin/tasq

Fork 0

Marc Rejohn Castillano 5cb6561924 added ruflo

2026-04-09 19:01:53 +08:00

14 KiB

Raw Blame History

AgentDB Simulation Troubleshooting Guide

Version: 2.0.0 Last Updated: 2025-11-30

Common issues, errors, and solutions for AgentDB simulations. Find quick fixes and workarounds for typical problems.

🚨 Quick Diagnostics

Run Self-Check

agentdb simulate --self-check

Checks:

CLI installation
Node.js version
Required dependencies
Write permissions
Memory availability

🔧 Installation Issues

"Command not found: agentdb"

Problem: CLI not in PATH after installation

Solution 1 - Global install:

npm install -g agentdb --force
npm list -g agentdb

Solution 2 - Add to PATH:

# macOS/Linux
echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.bashrc
source ~/.bashrc

# Windows
npm config get prefix
# Add that path to System Environment Variables

Solution 3 - Use npx:

npx agentdb simulate hnsw

"Cannot find module 'inquirer'"

Problem: Missing dependencies

Solution:

npm install -g inquirer chalk ora commander
agentdb simulate --wizard

Or: Reinstall AgentDB:

npm uninstall -g agentdb
npm install -g agentdb

TypeScript Compilation Errors

Problem: Build fails with TypeScript errors

Solution 1 - Clean build:

cd packages/agentdb/simulation
npm run clean
npm run build

Solution 2 - Check TypeScript version:

npm install -g typescript@latest
tsc --version  # Should be 5.0+

Solution 3 - Clear cache:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run build

⚠️ CLI Errors

"Scenario not found"

Error:

Error: Scenario 'hnws' not found

Problem: Typo in scenario name

Solution:

# List available scenarios
agentdb simulate --list

# Correct command
agentdb simulate hnsw  # Not 'hnws'

Available scenarios:

hnsw (not hnws, HNSW, or hnsw-exploration)
attention (not attention-analysis)
clustering
traversal
hypergraph
self-organizing
neural
quantum

"Invalid option"

Error:

Error: Unknown option '--node'
Did you mean '--nodes'?

Problem: Incorrect flag name

Solution: Check spelling and use autocomplete:

# Enable bash autocomplete
agentdb completion bash > /usr/local/etc/bash_completion.d/agentdb

# Or check CLI reference
agentdb simulate hnsw --help

Common typos:

--node → --nodes
--dimension → --dimensions
--iteration → --iterations
--backend ruvector → --backend ruvector (space, not =)

"Permission denied"

Error:

EACCES: permission denied, mkdir '/var/agentdb/reports'

Problem: No write permissions

Solution 1 - Change output directory:

agentdb simulate hnsw --output ~/agentdb-reports/

Solution 2 - Fix permissions:

sudo chown -R $(whoami) /var/agentdb
chmod -R 755 /var/agentdb

Solution 3 - Use local directory:

mkdir -p ./reports
agentdb simulate hnsw --output ./reports/

❌ Simulation Failures

"Simulation crashed mid-execution"

Error:

Building graph... [████████    ] 82%
Segmentation fault (core dumped)

Problem: Memory overflow or native code crash

Solution 1 - Reduce dataset size:

agentdb simulate hnsw \
  --nodes 10000 \    # Reduced from 100K
  --dimensions 128   # Reduced from 384

Solution 2 - Increase memory:

NODE_OPTIONS="--max-old-space-size=8192" \
  agentdb simulate hnsw

Solution 3 - Check logs:

tail -n 100 ~/.agentdb/simulation-error.log

"NaN in results"

Error:

Latency: NaN μs
Recall: NaN %

Problem: Division by zero or invalid data

Solution 1 - Validate input:

# Ensure nodes > 0
agentdb simulate hnsw --nodes 10000  # Not 0

# Ensure dimensions > 0
agentdb simulate hnsw --dimensions 384  # Not 0

Solution 2 - Check random seed:

# Use fixed seed for reproducibility
agentdb simulate hnsw --seed 42

Solution 3 - Report bug:

agentdb simulate hnsw \
  --verbose \
  --output ./debug-report.md 2> error.log
# Share error.log and debug-report.md

"Simulation timeout"

Error:

Timeout: Simulation exceeded 10 minutes

Problem: Dataset too large or infinite loop

Solution 1 - Increase timeout:

agentdb simulate hnsw \
  --timeout 3600000  # 1 hour in milliseconds

Solution 2 - Reduce complexity:

agentdb simulate hnsw \
  --nodes 50000 \
  --iterations 1

Solution 3 - Use simpler config:

agentdb simulate hnsw \
  --no-neural \
  --no-self-healing

🐌 Performance Issues

Simulation Runs Too Slowly

Problem: Takes minutes instead of seconds

Solution 1 - Check CPU usage:

# macOS
top -pid $(pgrep -f agentdb)

# Linux
htop -p $(pgrep -f agentdb)

Solution 2 - Reduce dataset:

agentdb simulate hnsw \
  --nodes 10000 \    # vs 100K
  --iterations 1     # vs 3

Solution 3 - Enable parallel processing:

agentdb simulate hnsw \
  --parallel \
  --threads 8  # Use all CPU cores

Solution 4 - Disable expensive features:

agentdb simulate hnsw \
  --no-benchmark \
  --no-validation \
  --simple  # No progress bars

Expected Performance

Dataset Size	Expected Duration	Tolerance
10K vectors	0.8-1.2s	±30%
100K vectors	4-6s	±30%
1M vectors	35-50s	±40%
10M vectors	5-8min	±50%

If much slower:

Check background processes
Ensure SSD (not HDD)
Check Node.js version (18+ recommended)
Update to latest AgentDB

💾 Memory Errors

"JavaScript heap out of memory"

Error:

FATAL ERROR: Reached heap limit Allocation failed
JavaScript heap out of memory

Problem: Dataset too large for available RAM

Solution 1 - Increase heap size:

export NODE_OPTIONS="--max-old-space-size=8192"
agentdb simulate hnsw --nodes 1000000

Solution 2 - Reduce dataset:

agentdb simulate hnsw --nodes 50000

Solution 3 - Use disk-based mode:

agentdb simulate hnsw --disk-mode

Memory Requirements:

Vectors	Dimensions	Memory Needed
10K	384	~15 MB
100K	384	~150 MB
1M	384	~1.5 GB
10M	384	~15 GB

Formula: Memory ≈ vectors × dimensions × 4 bytes × 1.2 (overhead)

"Cannot allocate memory"

Error:

Error: Cannot allocate memory
    at Buffer.allocUnsafe (buffer.js)

Problem: System RAM exhausted

Solution 1 - Check available RAM:

# macOS
vm_stat | grep "Pages free"

# Linux
free -h

Solution 2 - Close other applications:

# macOS
killall Chrome "Google Chrome" Safari

# Linux
killall chrome firefox

Solution 3 - Use streaming mode:

agentdb simulate hnsw --stream

📄 Report Generation

"Failed to write report"

Error:

Error: ENOENT: no such file or directory, open 'reports/hnsw.md'

Problem: Output directory doesn't exist

Solution:

mkdir -p ./reports
agentdb simulate hnsw --output ./reports/

"Report file is empty"

Problem: Report generated but 0 bytes

Solution 1 - Check disk space:

df -h

Solution 2 - Check permissions:

ls -la ./reports/
chmod 755 ./reports/

Solution 3 - Re-run with verbose:

agentdb simulate hnsw --verbose --output ./reports/

"Cannot open report in browser"

Problem: HTML report won't open

Solution 1 - Check file path:

# Use absolute path
open file:///$(pwd)/reports/hnsw.html

# Or relative
open ./reports/hnsw.html

Solution 2 - Convert to markdown:

agentdb simulate hnsw --format md
cat ./reports/hnsw.md

🧙 Wizard Issues

Wizard Won't Start

Error:

TypeError: inquirer.prompt is not a function

Problem: Incompatible inquirer version

Solution:

npm install -g inquirer@^8.0.0
agentdb simulate --wizard

Keyboard Input Not Working

Problem: Arrow keys print characters instead of navigating

Solution 1 - Use alternative keys:

j: Move down
k: Move up
n: Next
p: Previous

Solution 2 - Update terminal:

# macOS
brew install --cask iterm2

# Linux (Ubuntu)
sudo apt install gnome-terminal

# Windows
# Use Windows Terminal from Microsoft Store

Solution 3 - Use non-interactive mode:

agentdb simulate hnsw  # Direct command

Wizard Crashes

Error:

Unhandled promise rejection

Problem: Unexpected input or bug

Solution 1 - Check error log:

cat ~/.agentdb/wizard-error.log

Solution 2 - Run with verbose:

agentdb simulate --wizard --verbose 2> wizard-debug.log

Solution 3 - Skip wizard:

agentdb simulate hnsw  # Use direct command

Can't See Progress Bars

Problem: Progress bars render as text

Solution 1 - Disable spinners:

agentdb simulate --wizard --no-spinner

Solution 2 - Simple mode:

agentdb simulate --wizard --simple

Solution 3 - Check terminal:

echo $TERM  # Should show xterm-256color or similar

💻 Platform-Specific

macOS Issues

"Cannot verify developer"

Error:

"agentdb" cannot be opened because the developer cannot be verified

Solution:

# Allow in Security & Privacy
sudo xattr -d com.apple.quarantine $(which agentdb)

"Permission denied" (macOS)

Solution:

sudo npm install -g agentdb --unsafe-perm

Linux Issues

Missing Build Tools

Error:

gyp: No Xcode or CLT version detected!

Solution (Ubuntu/Debian):

sudo apt update
sudo apt install build-essential
npm install -g agentdb

Solution (Fedora/RHEL):

sudo dnf groupinstall "Development Tools"
npm install -g agentdb

SELinux Blocks Execution

Error:

SELinux is preventing agentdb from executing

Solution 1 - Allow execution:

sudo semanage fcontext -a -t bin_t "$(which agentdb)"
sudo restorecon -v "$(which agentdb)"

Solution 2 - Disable SELinux (not recommended):

sudo setenforce 0

Windows Issues

"agentdb is not recognized"

Solution 1 - Use full path:

%APPDATA%\npm\agentdb simulate hnsw

Solution 2 - Add to PATH:

setx PATH "%PATH%;%APPDATA%\npm"

Solution 3 - Use npx:

npx agentdb simulate hnsw

PowerShell Execution Policy

Error:

agentdb.ps1 cannot be loaded because running scripts is disabled

Solution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Line Ending Issues

Problem: Files have wrong line endings (CRLF vs LF)

Solution:

git config --global core.autocrlf input
git clone https://github.com/ruvnet/agentic-flow.git

🔬 Advanced Debugging

Enable Debug Mode

export DEBUG=agentdb:*
export AGENTDB_LOG_LEVEL=debug
agentdb simulate hnsw --verbose

Capture Full Logs

agentdb simulate hnsw \
  --verbose \
  2>&1 | tee simulation-debug.log

Memory Profiling

node --inspect-brk $(which agentdb) simulate hnsw
# Open chrome://inspect in Chrome

Check Dependencies

npm list -g agentdb
npm outdated -g

📊 Common Error Codes

Code	Meaning	Common Cause
`ENOENT`	File not found	Missing output directory
`EACCES`	Permission denied	No write permissions
`ENOMEM`	Out of memory	Dataset too large
`ETIMEDOUT`	Timeout	Simulation too slow
`ERR_INVALID_ARG_TYPE`	Wrong argument type	String instead of number

🆘 Getting Help

Still Stuck?

Check Documentation:
Search Issues:
- GitHub Issues
- Search for error message
Ask Community:
- GitHub Discussions
- Include: OS, Node version, command used, error log
Report Bug:
- Create new GitHub issue
- Include:
  - Command run
  - Full error message
  - agentdb --version
  - node --version
  - OS and version
  - Steps to reproduce

📋 Diagnostic Checklist

Before reporting an issue:

Run agentdb simulate --self-check
Update to latest version: npm update -g agentdb
Try with minimal dataset: --nodes 1000
Check available disk space: df -h
Check available RAM: free -h (Linux) or vm_stat (macOS)
Test with simple scenario: agentdb simulate hnsw
Review error logs: ~/.agentdb/*.log
Search existing issues on GitHub

🎯 Quick Fixes Summary

Problem	Quick Fix
Too slow	`--nodes 10000` (reduce dataset)
Out of memory	`NODE_OPTIONS="--max-old-space-size=8192"`
CLI not found	`npx agentdb simulate hnsw`
Report not generated	`mkdir -p ./reports`
Wizard broken	Use direct command instead
Permission denied	`--output ~/reports/`
TypeScript errors	`npm run clean && npm run build`

Still need help? Open an issue on GitHub →

14 KiB Raw Blame History Unescape Escape

AgentDB Simulation Troubleshooting Guide

🚨 Quick Diagnostics

Run Self-Check

📋 Table of Contents

🔧 Installation Issues

"Command not found: agentdb"

"Cannot find module 'inquirer'"

TypeScript Compilation Errors

⚠️ CLI Errors

"Scenario not found"

"Invalid option"

"Permission denied"

❌ Simulation Failures

"Simulation crashed mid-execution"

"NaN in results"

"Simulation timeout"

🐌 Performance Issues

Simulation Runs Too Slowly

Expected Performance

💾 Memory Errors

"JavaScript heap out of memory"

"Cannot allocate memory"

📄 Report Generation

"Failed to write report"

"Report file is empty"

"Cannot open report in browser"

🧙 Wizard Issues

Wizard Won't Start

Keyboard Input Not Working

Wizard Crashes

Can't See Progress Bars

💻 Platform-Specific

macOS Issues

"Cannot verify developer"

"Permission denied" (macOS)

Linux Issues

Missing Build Tools

SELinux Blocks Execution

Windows Issues

"agentdb is not recognized"

PowerShell Execution Policy

Line Ending Issues

🔬 Advanced Debugging

Enable Debug Mode

Capture Full Logs

Memory Profiling

Check Dependencies

📊 Common Error Codes

🆘 Getting Help

Still Stuck?

📋 Diagnostic Checklist

🎯 Quick Fixes Summary

14 KiB

Raw Blame History