818 lines
14 KiB
Markdown
818 lines
14 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
agentdb simulate --self-check
|
||
```
|
||
|
||
**Checks**:
|
||
- CLI installation
|
||
- Node.js version
|
||
- Required dependencies
|
||
- Write permissions
|
||
- Memory availability
|
||
|
||
---
|
||
|
||
## 📋 Table of Contents
|
||
|
||
- [Installation Issues](#installation-issues)
|
||
- [CLI Errors](#cli-errors)
|
||
- [Simulation Failures](#simulation-failures)
|
||
- [Performance Issues](#performance-issues)
|
||
- [Memory Errors](#memory-errors)
|
||
- [Report Generation](#report-generation)
|
||
- [Wizard Issues](#wizard-issues)
|
||
- [Platform-Specific](#platform-specific)
|
||
|
||
---
|
||
|
||
## 🔧 Installation Issues
|
||
|
||
### "Command not found: agentdb"
|
||
|
||
**Problem**: CLI not in PATH after installation
|
||
|
||
**Solution 1** - Global install:
|
||
```bash
|
||
npm install -g agentdb --force
|
||
npm list -g agentdb
|
||
```
|
||
|
||
**Solution 2** - Add to PATH:
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
npx agentdb simulate hnsw
|
||
```
|
||
|
||
---
|
||
|
||
### "Cannot find module 'inquirer'"
|
||
|
||
**Problem**: Missing dependencies
|
||
|
||
**Solution**:
|
||
```bash
|
||
npm install -g inquirer chalk ora commander
|
||
agentdb simulate --wizard
|
||
```
|
||
|
||
**Or**: Reinstall AgentDB:
|
||
```bash
|
||
npm uninstall -g agentdb
|
||
npm install -g agentdb
|
||
```
|
||
|
||
---
|
||
|
||
### TypeScript Compilation Errors
|
||
|
||
**Problem**: Build fails with TypeScript errors
|
||
|
||
**Solution 1** - Clean build:
|
||
```bash
|
||
cd packages/agentdb/simulation
|
||
npm run clean
|
||
npm run build
|
||
```
|
||
|
||
**Solution 2** - Check TypeScript version:
|
||
```bash
|
||
npm install -g typescript@latest
|
||
tsc --version # Should be 5.0+
|
||
```
|
||
|
||
**Solution 3** - Clear cache:
|
||
```bash
|
||
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**:
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
agentdb simulate hnsw --output ~/agentdb-reports/
|
||
```
|
||
|
||
**Solution 2** - Fix permissions:
|
||
```bash
|
||
sudo chown -R $(whoami) /var/agentdb
|
||
chmod -R 755 /var/agentdb
|
||
```
|
||
|
||
**Solution 3** - Use local directory:
|
||
```bash
|
||
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:
|
||
```bash
|
||
agentdb simulate hnsw \
|
||
--nodes 10000 \ # Reduced from 100K
|
||
--dimensions 128 # Reduced from 384
|
||
```
|
||
|
||
**Solution 2** - Increase memory:
|
||
```bash
|
||
NODE_OPTIONS="--max-old-space-size=8192" \
|
||
agentdb simulate hnsw
|
||
```
|
||
|
||
**Solution 3** - Check logs:
|
||
```bash
|
||
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:
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
# Use fixed seed for reproducibility
|
||
agentdb simulate hnsw --seed 42
|
||
```
|
||
|
||
**Solution 3** - Report bug:
|
||
```bash
|
||
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:
|
||
```bash
|
||
agentdb simulate hnsw \
|
||
--timeout 3600000 # 1 hour in milliseconds
|
||
```
|
||
|
||
**Solution 2** - Reduce complexity:
|
||
```bash
|
||
agentdb simulate hnsw \
|
||
--nodes 50000 \
|
||
--iterations 1
|
||
```
|
||
|
||
**Solution 3** - Use simpler config:
|
||
```bash
|
||
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:
|
||
```bash
|
||
# macOS
|
||
top -pid $(pgrep -f agentdb)
|
||
|
||
# Linux
|
||
htop -p $(pgrep -f agentdb)
|
||
```
|
||
|
||
**Solution 2** - Reduce dataset:
|
||
```bash
|
||
agentdb simulate hnsw \
|
||
--nodes 10000 \ # vs 100K
|
||
--iterations 1 # vs 3
|
||
```
|
||
|
||
**Solution 3** - Enable parallel processing:
|
||
```bash
|
||
agentdb simulate hnsw \
|
||
--parallel \
|
||
--threads 8 # Use all CPU cores
|
||
```
|
||
|
||
**Solution 4** - Disable expensive features:
|
||
```bash
|
||
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**:
|
||
1. Check background processes
|
||
2. Ensure SSD (not HDD)
|
||
3. Check Node.js version (18+ recommended)
|
||
4. 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:
|
||
```bash
|
||
export NODE_OPTIONS="--max-old-space-size=8192"
|
||
agentdb simulate hnsw --nodes 1000000
|
||
```
|
||
|
||
**Solution 2** - Reduce dataset:
|
||
```bash
|
||
agentdb simulate hnsw --nodes 50000
|
||
```
|
||
|
||
**Solution 3** - Use disk-based mode:
|
||
```bash
|
||
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:
|
||
```bash
|
||
# macOS
|
||
vm_stat | grep "Pages free"
|
||
|
||
# Linux
|
||
free -h
|
||
```
|
||
|
||
**Solution 2** - Close other applications:
|
||
```bash
|
||
# macOS
|
||
killall Chrome "Google Chrome" Safari
|
||
|
||
# Linux
|
||
killall chrome firefox
|
||
```
|
||
|
||
**Solution 3** - Use streaming mode:
|
||
```bash
|
||
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**:
|
||
```bash
|
||
mkdir -p ./reports
|
||
agentdb simulate hnsw --output ./reports/
|
||
```
|
||
|
||
---
|
||
|
||
### "Report file is empty"
|
||
|
||
**Problem**: Report generated but 0 bytes
|
||
|
||
**Solution 1** - Check disk space:
|
||
```bash
|
||
df -h
|
||
```
|
||
|
||
**Solution 2** - Check permissions:
|
||
```bash
|
||
ls -la ./reports/
|
||
chmod 755 ./reports/
|
||
```
|
||
|
||
**Solution 3** - Re-run with verbose:
|
||
```bash
|
||
agentdb simulate hnsw --verbose --output ./reports/
|
||
```
|
||
|
||
---
|
||
|
||
### "Cannot open report in browser"
|
||
|
||
**Problem**: HTML report won't open
|
||
|
||
**Solution 1** - Check file path:
|
||
```bash
|
||
# Use absolute path
|
||
open file:///$(pwd)/reports/hnsw.html
|
||
|
||
# Or relative
|
||
open ./reports/hnsw.html
|
||
```
|
||
|
||
**Solution 2** - Convert to markdown:
|
||
```bash
|
||
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**:
|
||
```bash
|
||
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:
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
agentdb simulate hnsw # Direct command
|
||
```
|
||
|
||
---
|
||
|
||
### Wizard Crashes
|
||
|
||
**Error**:
|
||
```
|
||
Unhandled promise rejection
|
||
```
|
||
|
||
**Problem**: Unexpected input or bug
|
||
|
||
**Solution 1** - Check error log:
|
||
```bash
|
||
cat ~/.agentdb/wizard-error.log
|
||
```
|
||
|
||
**Solution 2** - Run with verbose:
|
||
```bash
|
||
agentdb simulate --wizard --verbose 2> wizard-debug.log
|
||
```
|
||
|
||
**Solution 3** - Skip wizard:
|
||
```bash
|
||
agentdb simulate hnsw # Use direct command
|
||
```
|
||
|
||
---
|
||
|
||
### Can't See Progress Bars
|
||
|
||
**Problem**: Progress bars render as text
|
||
|
||
**Solution 1** - Disable spinners:
|
||
```bash
|
||
agentdb simulate --wizard --no-spinner
|
||
```
|
||
|
||
**Solution 2** - Simple mode:
|
||
```bash
|
||
agentdb simulate --wizard --simple
|
||
```
|
||
|
||
**Solution 3** - Check terminal:
|
||
```bash
|
||
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**:
|
||
```bash
|
||
# Allow in Security & Privacy
|
||
sudo xattr -d com.apple.quarantine $(which agentdb)
|
||
```
|
||
|
||
---
|
||
|
||
#### "Permission denied" (macOS)
|
||
|
||
**Solution**:
|
||
```bash
|
||
sudo npm install -g agentdb --unsafe-perm
|
||
```
|
||
|
||
---
|
||
|
||
### Linux Issues
|
||
|
||
#### Missing Build Tools
|
||
|
||
**Error**:
|
||
```
|
||
gyp: No Xcode or CLT version detected!
|
||
```
|
||
|
||
**Solution (Ubuntu/Debian)**:
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install build-essential
|
||
npm install -g agentdb
|
||
```
|
||
|
||
**Solution (Fedora/RHEL)**:
|
||
```bash
|
||
sudo dnf groupinstall "Development Tools"
|
||
npm install -g agentdb
|
||
```
|
||
|
||
---
|
||
|
||
#### SELinux Blocks Execution
|
||
|
||
**Error**:
|
||
```
|
||
SELinux is preventing agentdb from executing
|
||
```
|
||
|
||
**Solution 1** - Allow execution:
|
||
```bash
|
||
sudo semanage fcontext -a -t bin_t "$(which agentdb)"
|
||
sudo restorecon -v "$(which agentdb)"
|
||
```
|
||
|
||
**Solution 2** - Disable SELinux (not recommended):
|
||
```bash
|
||
sudo setenforce 0
|
||
```
|
||
|
||
---
|
||
|
||
### Windows Issues
|
||
|
||
#### "agentdb is not recognized"
|
||
|
||
**Solution 1** - Use full path:
|
||
```cmd
|
||
%APPDATA%\npm\agentdb simulate hnsw
|
||
```
|
||
|
||
**Solution 2** - Add to PATH:
|
||
```cmd
|
||
setx PATH "%PATH%;%APPDATA%\npm"
|
||
```
|
||
|
||
**Solution 3** - Use npx:
|
||
```cmd
|
||
npx agentdb simulate hnsw
|
||
```
|
||
|
||
---
|
||
|
||
#### PowerShell Execution Policy
|
||
|
||
**Error**:
|
||
```
|
||
agentdb.ps1 cannot be loaded because running scripts is disabled
|
||
```
|
||
|
||
**Solution**:
|
||
```powershell
|
||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||
```
|
||
|
||
---
|
||
|
||
#### Line Ending Issues
|
||
|
||
**Problem**: Files have wrong line endings (CRLF vs LF)
|
||
|
||
**Solution**:
|
||
```bash
|
||
git config --global core.autocrlf input
|
||
git clone https://github.com/ruvnet/agentic-flow.git
|
||
```
|
||
|
||
---
|
||
|
||
## 🔬 Advanced Debugging
|
||
|
||
### Enable Debug Mode
|
||
|
||
```bash
|
||
export DEBUG=agentdb:*
|
||
export AGENTDB_LOG_LEVEL=debug
|
||
agentdb simulate hnsw --verbose
|
||
```
|
||
|
||
---
|
||
|
||
### Capture Full Logs
|
||
|
||
```bash
|
||
agentdb simulate hnsw \
|
||
--verbose \
|
||
2>&1 | tee simulation-debug.log
|
||
```
|
||
|
||
---
|
||
|
||
### Memory Profiling
|
||
|
||
```bash
|
||
node --inspect-brk $(which agentdb) simulate hnsw
|
||
# Open chrome://inspect in Chrome
|
||
```
|
||
|
||
---
|
||
|
||
### Check Dependencies
|
||
|
||
```bash
|
||
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?
|
||
|
||
1. **Check Documentation**:
|
||
- [Quick Start Guide](QUICK-START.md)
|
||
- [CLI Reference](CLI-REFERENCE.md)
|
||
- [Custom Simulations](CUSTOM-SIMULATIONS.md)
|
||
|
||
2. **Search Issues**:
|
||
- [GitHub Issues](https://github.com/ruvnet/agentic-flow/issues)
|
||
- Search for error message
|
||
|
||
3. **Ask Community**:
|
||
- [GitHub Discussions](https://github.com/ruvnet/agentic-flow/discussions)
|
||
- Include: OS, Node version, command used, error log
|
||
|
||
4. **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 →](https://github.com/ruvnet/agentic-flow/issues)
|