Troubleshooting

Issues during an Operayde install cluster around networking, DNS, and IdP configuration. A pragmatic checklist below, in the order we usually walk through it with customers.

Appliance won’t enrol

• Verify outbound HTTPS to central.operayde.com:443 is allowed.
• Check the token hasn’t expired (48 h default TTL) or been used — tokens are single-use; ask us to mint a fresh one if in doubt.
• Confirm the token was entered for the correct tenant/appliance.

# From a laptop on the same LAN as the appliance:
curl -sv https://central.operayde.com/v1/health | head

If curl succeeds but the appliance can’t reach us, the appliance itself isn’t being allowed out by the firewall — ask your network team.

Staff can’t sign in

• Check appliance.<your-domain> resolves to the appliance LAN IP.
• Confirm the OIDC client in your IdP has the appliance callback URL pinned.
• Make sure the tenant ID in your IdP’s tid claim matches the enrolment.

429 from the gateway

The appliance is healthy; the tenant or key budget is exhausted. Check Virtual keys → Usage in the portal for the offending key, or raise the budget: scope on a new key.

Health checks failing

Every service exposes /healthz on its local port. The appliance dashboard aggregates them into a single “green / degraded / red” indicator, but for diagnostics:

# On the appliance:
systemctl status operayde-workspace-runtime
systemctl status operayde-appliance-gateway
systemctl status operayde-tunnel-agent
systemctl status operayde-audit-emitter

Any non-active (running) state warrants an incident. Collect journalctl -u <service> -n 200 and attach to the ticket.

When to call us

• systemctl shows repeated restart loops.
• operayde-workspace-runtime runs out of memory during RAG ingest (indicates oversized docs; we have workarounds).
• The appliance refuses to unlock or boot normally.

Open an incident from Portal → Fleet → [appliance] → Open incident. Include logs and screenshots where possible.