Troubleshooting

Gateway Issues

Gateway won't start

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

RPC probe fails

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

MODULE_VERSION mismatch

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

Telegram bot not responding

See Channel Troubleshooting.

WhatsApp connection drops

WhatsApp Web sessions expire. Re-scan the QR code:

argent channels add whatsapp

Discord "Used disallowed intents"

Enable Privileged Gateway Intents in the Discord Developer Portal under your application's Bot settings. See Discord setup.

Memory Issues

Memory search returns no results

• 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

Memory database locked

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

Rate limit errors

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.

"Context window exceeded"

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

High CPU usage

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.

Slow responses

• 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 on GitHub