Skip to content

Troubleshooting

This guide covers common operational failure modes and safe diagnostic steps.

Important

Do not paste secrets (tokens, API keys, webhook secrets) into tickets, chat, terminals with shared logging, or documentation.

Quick Checks

Axis UI

  • Verify you can sign in.
  • Confirm the agent appears under the expected environment.
  • Check Diagnostics and Analytics for agent health and recent telemetry.

Linux host (systemd)

sudo systemctl status velikey-aegis --no-pager
sudo journalctl -u velikey-aegis -n 200 --no-pager
curl -fsS http://127.0.0.1:9080/health
curl -fsS http://127.0.0.1:9080/metrics | head

Kubernetes

kubectl -n <namespace> get ds -l app.kubernetes.io/component=agent
kubectl -n <namespace> get pods -l app.kubernetes.io/component=agent -o wide
kubectl -n <namespace> logs ds/<release>-agent --since=30m

Strict TLS Errors

Common symptoms:

  • certificate signed by unknown authority
  • hostname/SAN mismatch
  • unable to verify the first certificate

Safe diagnostics:

# Inspect the server certificate chain.
openssl s_client -connect <control-plane-host>:8443 -servername <control-plane-host> -showcerts </dev/null

Typical fixes:

  • Ensure the agent control plane URL matches the certificate's SAN (hostname or IP SAN).
  • If using a private CA, configure the agent with the CA bundle.
  • Helm: set agent.controlPlaneCa.existingSecretName to mount a CA cert secret.
  • Avoid disabling TLS validation except as a short-lived diagnostic.

Enrollment and Token Issues

Common symptoms:

  • agent enroll fails with 401/403
  • repeated enroll attempts with a "token invalid" message
  • enroll succeeds once, then fails on reinstall

Notes:

  • Bootstrap tokens are intended to be single-use. If you reinstall or clone a host image, generate a new token/script.
  • Tokens are tenant-scoped. A token created in one organization must not be reused for another.

Kubernetes checks (no secret values):

kubectl -n <namespace> describe secret <agent-secret-name>

Linux checks (avoid printing the token value):

  • Confirm the agent config points to the correct control plane URL.
  • If you suspect the token is wrong or reused, generate a new install script and re-enroll.

CSP/SSO Misconfiguration

Common symptoms:

  • redirect_uri_mismatch during SSO sign-in
  • "no matching provider" / provider not configured
  • sign-in loops

Checks:

  • Confirm the redirect/callback URL configured in your IdP matches Axis.
  • Typical callback path: https://<axis-host>/api/auth/callback/<provider>
  • Ensure the IdP client is configured for the correct environment (staging vs production).

Stripe Webhooks Not Firing (Test Mode)

Common symptoms:

  • billing status not updating
  • webhook deliveries missing in Stripe dashboard

Checks:

  • Stripe Dashboard: verify the endpoint is created in the correct mode (test vs live).
  • Confirm the endpoint URL is reachable from the public internet.
  • Verify your deployment is using the correct webhook signing secret for the mode.

Email Delivery Issues (SES Sandbox)

Common symptoms:

  • invitations or alerts never arrive
  • emails only deliver to verified recipients

Checks:

  • SES sandbox mode restricts sending.
  • Verify sender identity (domain or email) and DKIM/SPF records.
  • Review bounce/complaint metrics and suppression lists.

What to Send Support

Provide:

  • timestamps and time zone
  • organization/environment name
  • agent ID and host/k8s node name
  • relevant error messages (redacted)

Do not provide:

  • bootstrap tokens
  • API keys
  • webhook signing secrets