Operations

Troubleshooting

Start from the symptom you can see. Almost every issue resolves to one of four causes: DNS or firewall, a missing secret, a service that did not come back after a restart, or a node that cannot reach the panel on :443.

§1

Always run this first#

on the panel VPS

vortexa status        # services, ports, version, cert expiry
vortexa version       # installed vs latest release
systemctl status autoscript-agent nginx
nginx -t
journalctl -u autoscript-agent -n 100 -o cat

vortexa status answers most questions on its own: it prints which units are running, which ports are bound, the certificate expiry and the installed release.

§2

Panel URL doesn't load#

Confirm DNS for the panel hostname resolves to this VPS (dig +short panel.example.com).
Confirm 80 and 443 are open both in the OS firewall (UFW/firewalld/nftables) and in your cloud provider's security group.
Run nginx -t — a bad vhost keeps the old config running while the new one silently never loads.
If nginx is fine but you get 502, the web process is down: vortexa restart.

§3

TLS certificate failed to issue#

acme.sh uses the HTTP-01 challenge, so port 80 must reach the VPS directly during issuance.

On a Cloudflare-proxied hostname, temporarily turn off Always Use HTTPS (and the orange cloud, if a redirect rule still intercepts /.well-known/), then run vortexa repair.
Remove any redirect that sends port 80 to HTTPS before the challenge path is served.
Let's Encrypt rate limits are per registered domain per week — during testing use a subdomain you are not re-issuing repeatedly.

Expiring certificate

The Infrastructure page flags approaching expiry from the cert metadata pushed on heartbeat. Treat it as high priority: nginx and Xray refuse the vhost once the certificate lapses.

§4

A node shows offline or stuck installing#

Offline

on the node VPS

systemctl status grvpn-agent
journalctl -u grvpn-agent -n 100 -o cat
curl -sS -o /dev/null -w '%{http_code}\n' https://panel.example.com/api/status

If the curl does not return 200, the node cannot reach the panel — fix egress or DNS on the node first. If it can reach the panel but stays offline, re-run the node installer from Nodes → Add node to re-register and re-pin.

Stuck “installing”

The node never wrote install-complete.json, or one of the install phases failed. Check journalctl -u autoscript-node -f -o cat on the box and look for the first failing phase — later failures are usually cascades.

Node returns “no secret for node …”

The panel has no secret for that node id. Set NODE_SECRET_<NODE_ID> or NODE_SHARED_SECRET in /etc/autoscript/agent.env and run vortexa restart. The route answers with configRequired: true rather than a 5xx, so the console stays usable.

§5

401 responses from the node plane#

Response	Cause	Fix
missing signature	Agent sent no x-timestamp / x-signature.	Agent is outdated or misconfigured — reinstall it.
stale request	Clock skew above 300 seconds.	Enable NTP on the node: `timedatectl set-ntp true`.
bad signature	Node and panel hold different secrets.	Re-copy the secret and restart both sides.
replayed request	The same signature was submitted twice.	Usually a retry loop or a duplicated agent instance — check for two running units.

§6

Update didn't change the version#

bash

vortexa version
vortexa update

The CLI only installs tagged GitHub releases. If the installed release still lags, the release is not published yet. Remote nodes never self-update — update them from the panel's Update action; only the panel's own local node updates itself.

§7

agent.env: command not found#

symptom

/etc/autoscript/agent.env: line 12: Vortexa: command not found

An env value containing a space was written unquoted (for example BRAND_NAME=GRVPN Vortexa). This is fixed in the installer — all values are single-quoted. On an existing install, quote the offending line and run vortexa restart.

§8

Usage or speed limits look wrong#

Usage arrives on heartbeat, so a node that is offline simply stops reporting — the counters are not lost, they resume on the next successful beat.
A speed cap that “does nothing” is usually a CDN-fronted client whose real address never appears in ss output, so per-IP HTB cannot match it. Mark-based shaping should catch it — verify the xray.service override still grants CAP_NET_ADMIN.
On OpenVZ/LXC the host kernel can block tc/BBR entirely; shaping degrades instead of aborting.

§9

Telegram bot is silent#

Check the token and that only one instance is polling — two pollers make both look dead.
Admin actions from the bot need BOT_INTERNAL_TOKEN to match the panel's value, otherwise every admin call returns 401.
Restart with vortexa restart and watch journalctl -u autoscript-bot -f -o cat.

§10

Still stuck#

Collect this before asking for help — it answers the first five questions anyone will ask:

bash

vortexa version
vortexa status
journalctl -u autoscript-agent -n 200 -o cat > /tmp/agent.log
nginx -t 2>&1 | tail -5

Never paste secrets

Strip JWT_SECRET, BOT_INTERNAL_TOKEN, node secrets and bot tokens from any log you share.

autoscript CLI

Every command available on the VPS.

FAQ

Shorter answers to common questions.