Common Errors

Last updated 4 min read
Report issue

Common Errors#

Quick reference for the errors we see most often in support. If your error isn't here, please open a GitHub issue or email [email protected].

Agent install / enrollment#

curl: (60) SSL certificate problem#

Your VM's CA bundle is out of date. On Ubuntu/Debian:

BASH
sudo apt update && sudo apt install ca-certificates && sudo update-ca-certificates

Then re-run the install command.

enrollment failed: token expired#

Enrollment tokens expire 24 hours after creation. Get a fresh one from the panel (Settings → Tokens → New) and re-run install.

enrollment failed: token already used#

Enrollment tokens are single-use by default. Either:

  • Get a new token, or
  • Click "Allow reuse" on the existing token in the panel (only do this for staging/test environments)

agent installed but not appearing in panel#

Most common cause: outbound 443 to *.gritiva.com is blocked by your firewall. Test:

BASH
curl -v https://panel.gritiva.com/api/v1/health

If that times out, fix your firewall. If it succeeds, check:

BASH
sudo journalctl -u gritiva-agent -n 50 --no-pager | grep -iE 'connect|reject|deny'

Scope lifecycle#

gritivactl scope create: failed to create netns: operation not permitted#

The agent doesn't have CAP_NET_ADMIN or CAP_SYS_ADMIN. Verify the systemd unit:

BASH
sudo grep -E 'AmbientCapabilities|CapabilityBoundingSet' /etc/systemd/system/gritiva-agent.service

Should include CAP_NET_ADMIN and CAP_SYS_ADMIN. If missing, the install script needs to be re-run with --force-systemd-overwrite.

scope X: died unexpectedly, restart_count=5, giving up#

The agent gave up restarting a scope's main process after 5 consecutive crashes. Investigate:

BASH
sudo gritivactl scope logs my-app --since 10m

Common causes: out-of-memory in the cgroup (raise --mem), missing dependency in the docker image, port conflict with another scope.

Domain / DRM#

domain add: cloudflare API: 1003 Invalid or missing zone id#

The domain's apex isn't registered in your Cloudflare account, OR the API token in /etc/gritiva/agent.toml doesn't have access to that zone. Add the zone in Cloudflare dashboard first, then check token permissions (Zone → Read + Edit on that specific zone).

domain returning 502 Bad Gateway#

Cloudflared can reach the tunnel but nginx-in-scope isn't responding. Check:

  1. Is the scope running? sudo gritivactl scope status my-app
  2. Is the app listening on the port you specified? sudo gritivactl scope exec my-app -- ss -tlnp | grep 8080
  3. Is nginx-in-scope started? sudo gritivactl scope exec my-app -- systemctl status nginx

domain stuck in "provisioning" status#

The DRM reconciler is in a back-off loop. Tail the agent logs:

BASH
sudo journalctl -u gritiva-agent -n 100 --no-pager | grep -i drm

Common: Cloudflare rate-limit (wait 60s), expired CF API token (rotate in panel), nginx-in-scope can't bind port (something else is on it).

Mesh / gmesh#

gmeshctl peer list: peer X stuck in CONNECTING for >5 minutes#

Almost always: the remote scope is missing a wg-gmesh interface inside its netns. The cause was traced in the 2026-05-14 mesh-stuck-peer postmortem. Manual fix:

BASH
sudo gritivactl scope mesh disconnect my-app --peer remote-vm:other-scope
sudo gritivactl scope mesh connect my-app --peer remote-vm:other-scope --force

If still stuck after retry, file a bug — it's a real reconciler bug.

agent: NRestarts=12 / hour, mesh stuck#

You're hitting the agent crash loop (postmortem on 2026-05-14). Verify your agent is on PR #55 or later:

BASH
gritivactl version  # should be >= 2.5.0

If older, run the install script again with --upgrade.

Panel / web UI#

Cannot login: too many failed attempts#

Lockout is 15 minutes after 5 failed attempts. Wait it out, OR use the password-reset link in the login page.

Panel showing "VM offline" but I can SSH in#

The agent's WebSocket to the panel got disconnected. Check on the host:

BASH
sudo systemctl status gritiva-agent
sudo journalctl -u gritiva-agent -n 50 --no-pager | tail

If the agent is running but offline in panel, restart it:

BASH
sudo systemctl restart gritiva-agent

Should reconnect within 30 seconds. If not, the agent may have been bypassed by an outbound firewall change.

Docs system (docs.gritiva.com)#

LLM drafter returning generic content#

The meta field is silently ignored by the planner (known issue). Workaround: redraft with notes prefixed "MUST INCLUDE EXACTLY" and provide every literal command/term you want in the output.

Still need help?#

[email protected] (Pro+) ・ Discord (TBD, Free) ・ GitHub issues