Troubleshooting

Start Here

When something is wrong, run the full diagnostics first:

agentrix doctor

It shows version info, configuration, environment variables, authentication status, dependency status, and daemon state in one output. Most problems are visible here.

---

Daemon Won't Start

Missing dependencies

⚠️  Missing Critical Dependencies
Cannot start daemon. Missing: ripgrep

Install the missing tool (see Dependencies), then run agentrix start again.

Stale daemon state

If a previous daemon crashed, its .state.json lock file may still exist. agentrix start cleans this up automatically, but if it does not:

agentrix stop        # attempt a clean stop
agentrix killall     # kill any remaining agentrix processes
agentrix start

Daemon exits immediately after starting

✗ Daemon exited shortly after startup

Check the daemon log for the root cause:

cat ~/.agentrix/logs/daemon.log | tail -30

Common causes:

Log message	Fix
Machine binding revoked	Run agentrix logout and authenticate again
Auth / network errors	Check connectivity to agentrix.xmz.ai and proxy settings

---

Authentication Problems

Machine binding revoked

Machine binding revoked
Run `agentrix logout` and bind again.

Your machine's token was revoked from the web app or expired. Unbind and re-authenticate:

agentrix logout
agentrix start

Browser does not open

If the browser does not launch automatically, copy the URL printed to the terminal and open it manually:

If the browser did not open, please copy and paste this URL:
https://agentrix.xmz.ai/auth/machine?...

Headless environment (no browser)

Use CLOUD_AUTH_TOKEN to skip the browser flow:

CLOUD_AUTH_TOKEN=<your-token> agentrix start

---

Dependency Not Found

Even though a tool is installed, the CLI may report it as missing if the binary is not on PATH.

# Check where npm puts global binaries
npm config get prefix

# Add to PATH (paste into ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$(npm config get prefix)/bin"

Then reload your shell and try again:

source ~/.zshrc   # or source ~/.bashrc
agentrix doctor

---

Stuck or Zombie Sessions

# List active sessions
agentrix ls

# Stop a specific session
agentrix kill task-abc123

# Kill all runaway agentrix processes
agentrix killall

---

Log Files

Log	Location
Daemon log	~/.agentrix/logs/daemon.log
Worker log	~/.agentrix/logs/worker-<taskId>.log

# Follow the daemon log live
tail -f ~/.agentrix/logs/daemon.log

# Check the last 30 lines
tail -30 ~/.agentrix/logs/daemon.log

Security note: CLI 0.51.3 and earlier could write credentials embedded in Git URLs to the daemon log when DEBUG logging was enabled. If you used an authenticated Git URL with an affected version, upgrade the CLI and rotate the exposed access token or password, including credentials retained in archived logs or support bundles.

---

Reset / Reinstall

To start fresh, stop the daemon, remove credentials and state, then re-authenticate:

agentrix stop
agentrix killall

# Remove only credentials (keeps settings)
rm ~/.agentrix/credentials.json

# Or remove everything
rm -rf ~/.agentrix

# Re-authenticate
agentrix start

To reinstall the CLI:

npm install -g @agentrix/cli@latest
agentrix start

---

Proxy / Network Issues

If your network requires a proxy, configure it in ~/.agentrix/settings.json:

{
  "daemonEnv": {
    "enabled": true,
    "variables": {
      "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
      "NO_PROXY": "localhost,127.0.0.1"
    }
  }
}

Restart the daemon after saving:

agentrix stop && agentrix start

See Settings for the full daemonEnv reference.

---

Checking Environment

agentrix doctor

The Environment Variables section shows what Agentrix sees at runtime:

🌍 Environment Variables
AGENTRIX_HOME_DIR: not set
AGENTRIX_SERVER_URL: not set
DEBUG: not set
NODE_ENV: not set

If AGENTRIX_SERVER_URL points to the wrong host, override it:

export AGENTRIX_SERVER_URL=https://agentrix.xmz.ai
agentrix start