Skip to main content

​
Gateway Issues

Symptom: argent gateway start exits immediately or shows an error.Check:
argent gateway logs --level error
Common causes:
  • Port 18789 is already in use: lsof -i :18789
  • Node.js version mismatch: verify node --version shows v22+
  • Config syntax error: argent config validate
Symptom: argent gateway status shows “running” but “RPC probe: failed”.Common cause: Native module ABI mismatch. The gateway is using a different Node.js version than the one used to compile native modules.Fix:
# Check which node the plist uses (macOS)
grep -A1 ProgramArguments ~/Library/LaunchAgents/ai.argent.gateway.plist | grep node

# Should match nvm node, not Homebrew
# Fix: edit the plist to use nvm node path
# Then reload:
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.argent.gateway.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.argent.gateway.plist
Symptom: Error log shows NODE_MODULE_VERSION mismatch.Fix: Rebuild native modules against the correct Node.js version:
cd /path/to/argentos
pnpm rebuild better-sqlite3

​
Channel Issues

WhatsApp Web sessions expire. Re-scan the QR code:
argent channels add whatsapp
Enable Privileged Gateway Intents in the Discord Developer Portal under your application’s Bot settings. See Discord setup.

​
Memory Issues

  • Check that memories exist: argent memory stats
  • Use simpler queries: single keywords work best with FTS5
  • Try OR syntax for multi-word queries: "telegram OR discord"
  • Verify the database is accessible: ls -la ~/.argentos/memory.db
Another process may be holding a lock:
# Check for processes using the database
fuser ~/.argentos/memory.db

# Restart the gateway to release locks
argent gateway restart

​
Model/API Issues

The failover system should handle this automatically. Check profile status:
argent status
If all profiles are in cooldown, wait for the cooldown to expire or add more auth profiles.
The conversation has grown too large. This triggers automatic compaction, but if it persists:
# Clear the current session
argent sessions clear <session-id>

​
Performance Issues

Check for zombie processes:
ps aux | grep "stream-json"
The health check reaper should clean these up every 60 seconds. If they persist, restart the gateway.
  • Check model tier: LOCAL tier is fastest, POWERFUL is slowest
  • Check for API latency in gateway logs
  • Verify network connectivity to API providers

​
Getting More Help

If these steps do not resolve your issue:
1

Collect diagnostics

argent status --json
2

Gather logs

argent gateway logs --last 200
3

Open an issue

File a report on GitHub.