Skip to main content

​
Troubleshooting

​
First 60 seconds

Run these in order: 
gensparx status
gensparx status --all
gensparx gateway probe
gensparx logs --follow
gensparx doctor
If the gateway is reachable, deep probes: 
gensparx status --deep

​
Common “it broke” cases

​
gensparx: command not found

Almost always a Node/npm PATH issue. Start here:

​
Installer fails (or you need full logs)

Re-run the installer in verbose mode to see the full trace and npm output: 
curl -fsSL https://gensparx.com/install.sh | bash -s -- --verbose
For beta installs: 
curl -fsSL https://gensparx.com/install.sh | bash -s -- --beta --verbose
You can also set OPENCLAW_VERBOSE=1 instead of the flag.

​
Gateway “unauthorized”, can’t connect, or keeps reconnecting

​
Control UI fails on HTTP (device identity required)

​
docs.gensparx.com shows an SSL error (Comcast/Xfinity)

Some Comcast/Xfinity connections block docs.gensparx.com via Xfinity Advanced Security. Disable Advanced Security or add docs.gensparx.com to the allowlist, then retry.

​
Service says running, but RPC probe fails

​
Model/auth failures (rate limit, billing, “all models failed”)

​
/model says model not allowed

This usually means agents.defaults.models is configured as an allowlist. When it’s non-empty, only those provider/model keys can be selected.
  • Check the allowlist: gensparx config get agents.defaults.models
  • Add the model you want (or clear the allowlist) and retry /model
  • Use /models to browse the allowed providers/models

​
When filing an issue

Paste a safe report: 
gensparx status --all
If you can, include the relevant log tail from gensparx logs --follow.