Skip to main content

​
First: what to grab before opening a support ticket

Three pieces of context cover 80% of cases:
Attach those to support@radarhq.io along with your license id (visible in the log line radar-hub: license verified license_id=lic_...).

​
”Can’t reach the web app” / first-install issues

​
Pod stuck pending

Most common causes:
  • Image pull error - your registry mirror isn’t reachable, or the imagePullSecrets ref is missing. Confirm kubectl -n radar-hub describe pod <pod> shows the secret under imagePullSecrets, and read the pull error in its events.
  • No node fits - nodeSelector / tolerations / affinity settings exclude every node. Drop them while debugging.
  • PVC pending - only the bundled eval Postgres claims a PVC (10Gi ReadWriteOnce from the default StorageClass). kubectl -n radar-hub describe pvc shows why. With no default StorageClass, set postgres.bundled.persistence.storageClass or create a default class. See EKS Auto Mode for the common EKS case.

​
EKS Auto Mode: Postgres PVC stays Pending

EKS Auto Mode provisions volumes with the ebs.csi.eks.amazonaws.com driver. A cluster whose only StorageClass is the legacy gp2 (kubernetes.io/aws-ebs provisioner), with none marked default, never binds the bundled Postgres PVC, so Postgres and the hub never start. Create a default StorageClass for the Auto Mode driver, then delete the pending PVC and Postgres pod (or reinstall):
Or keep your cluster default unchanged and set postgres.bundled.persistence.storageClass=auto-ebs-sc on the release.

​
Hub Pod stuck in Init: migrate failed

Failure modes:
  • relation "X" does not exist - extremely rare since the chart’s 000_baseline.sql migration bootstraps the schema automatically. Do not drop the database. Collect the migrate initContainer logs (kubectl -n radar-hub logs deploy/radar-hub-hub -c migrate) and contact support; if this is a fresh install with no data yet, a clean empty database and a pod restart re-applies the schema.
  • password authentication failed - the DSN is wrong. kubectl get secret <pg-secret> -o yaml | grep dsn to confirm.
  • connection refused - the DB isn’t reachable from this namespace. Test with a one-off kubectl run -ti --rm pgcheck --image=postgres:17-alpine -- psql <dsn> -c 'SELECT 1'.

​
Hub Pod CrashLoopBackOff at boot

(Use --previous because the main container dies on misconfig; the current pod may not have logs yet.)
  • no auth configured: set WORKOS_API_KEY ... or RADAR_HUB_OIDC_* ... or RADAR_HUB_BOOTSTRAP_ADMIN_* ... (log.Fatal at boot) - neither WorkOS nor OIDC nor break-glass is wired. At least one is required. Fix in chart values: auth.breakGlass.email + password or OIDC issuer + secret.
  • HUB_COOKIE_PASSWORD must be at least 32 bytes - the value is too short. Regenerate with openssl rand -base64 48.

​
Control plane starts but /api/config 503s

  • db connection: ... - container is up, DB is unreachable mid-flight. Same checks as the migrate failures above.

​
Web app loads but every request 401s

The web app fetches /api/account on mount. If that 401s in a fresh browser:
  • Cookie not set - confirm you actually completed the break-glass login or OIDC roundtrip. The login response should Set-Cookie: radar-hub-session=....
  • CORS / SameSite mismatch - if your web app host differs from the control plane host (split origins), the cookie won’t flow. Single-host install is the supported MVP shape.
  • HUB_ALLOWED_ORIGINS doesn’t include your origin - the control plane strips disallowed origins server-side.

​
Auth issues

​
”Invalid credentials” on break-glass login

  • Email is case-insensitive, but trim whitespace.
  • Bcrypt hash format must start with $2y$, $2a$, or $2b$. If it starts with anything else, the chart will reject it at boot - check kubectl -n radar-hub logs deploy/radar-hub-hub | grep break-glass.
  • Plaintext password with a ' or $ not properly escaped via --set will produce a hash for a different string than you intended. Use --set-string or move secrets to a Secret.

​
OIDC redirect loop

  • auth.oidc.callbackURL must EXACTLY match what’s registered with the IdP. Case, scheme, port, trailing slash all matter.
  • Discover-doc errors at boot: kubectl -n radar-hub logs | grep oidc. Common cause: corporate proxy intercepting outbound HTTPS - the control plane needs direct egress to the IdP’s .well-known/openid-configuration.

​
”OIDC silent refresh not supported”

That’s not an error. It comes from the Cloud refresh path, which self-managed does not use. Self-Managed sessions end after 7 days, or 24 hours unused, and the user signs in again through the IdP. To refresh IdP groups during a session, see refresh tokens.

​
Users are signed out after a day

That’s the idle limit: a session unused for 24 hours ends. Raise auth.session.maxInactive (for example "72h") - see Sessions.

​
503 errors with useRefreshToken on

The hub could not reach the IdP to refresh a user’s ID token, or the IdP returned 429/5xx. The session is kept and the next request retries. Check egress from the hub to the IdP’s token endpoint. kubectl -n radar-hub logs deploy/radar-hub-hub | grep -i refresh shows the error.

​
A user has the wrong role

Roles are managed in the hub, not from IdP groups. The first user to sign in bootstraps as owner; everyone else joins as auth.oidc.defaultRole (default member). An owner promotes or demotes anyone from Settings → Organization → Members in the web app.

​
License issues

​
”license is invalid (bad signature or claims)”

  • The build was cut against a different public key than the one signed your JWT. Confirm the radar-hub image tag matches what your account team issued the license for.
  • The JWT was truncated when pasted. Whole token is one base64 line - watch for \n mid-string.

​
”license is expired”

The control plane keeps serving in full for a grace period, then the web console closes for everyone until a valid license is installed. Break-glass sign-in still works, but it does not reopen the console. Your clusters, the tunnel, your agents and API/token traffic are unaffected throughout. To recover, install a valid license through the Secret or the Helm values; see Rotation. There is no way to do it from the console. If this deployment is cloud-managed, it renews itself. Check outbound HTTPS to your configured license server (hub.licenseServer, default https://api.radarhq.io). To replace the license by hand:
  1. Get a renewed JWT from your account team.
  2. Update the Helm value (license.key) or rotate the existing Secret.
  3. Restart the hub pod so it reads the new file: kubectl -n radar-hub rollout restart deploy/radar-hub-hub.

​
”embedded license public key is the all-zero placeholder”

The radar-hub binary was built without the production public key embedded. This shouldn’t happen in any image you pulled from ghcr.io/skyhook-dev/radar-hub. If you see it, you’re probably running a self-built image - the chart’s image references should point at the official release.

​
Cluster-side issues

​
”Cluster shows disconnected” but the in-cluster Radar is running

In the customer cluster:
Look for:
  • cloud: dial wss://radar.acme.example/agent: ... - DNS / network from the customer cluster to the control plane.
  • cloud: token rejected - the cluster token was rotated or revoked. Re-mint via the web app’s “Add cluster” wizard.
  • cloud: tls handshake failed - the control plane’s TLS cert doesn’t validate from the customer cluster. Confirm cert chain.

​
Cluster connects but tunnel calls hang

  • The control plane’s proxy_read_timeout is 600s by default. Long Helm catalog scans or large audit pulls can exceed that. Bump via ingress.annotations for nginx-ingress.
  • Some on-prem load balancers strip Connection: upgrade at L7. The Ingress class needs to support WebSocket. nginx-ingress does by default; some HA-Proxy / F5 deployments need explicit config.

​
Performance issues

​
/api/fleet/* is slow

Fleet calls fan out to every connected cluster in parallel with a 7s per-cluster timeout + 12s overall cap. If you have hundreds of clusters and the slowest one dominates, the call returns partial results with the slow ones flagged. The web app’s coverage footer shows offline / errored clusters - that’s the signal, not a bug.

​
radar-hub Pod CPU at 100%

  • Audit reads filter on the retention window, and a daily sweep deletes rows older than RADAR_HUB_AUDIT_RETENTION_DAYS. Watch radarhub_audit_events_total - if it’s into the millions and queries are slow, reduce RADAR_HUB_AUDIT_RETENTION_DAYS.
  • Tunnel-session count: hundreds of clusters connected to a single replica is fine; thousands isn’t tested.

​
Postgres slow on audit reads

Index on audit_events(org_id, created_at DESC) is shipped by default. If a customer’s audit volume is enormous, ensure that index is healthy:

​
Last resort

  • helm get values radar-hub --namespace radar-hub to confirm what’s actually configured.
  • kubectl -n radar-hub describe deploy/radar-hub-hub for the full env-var list as Kubernetes sees it.
  • Toggle break-glass admin if OIDC is wedged - it’s always available even when OIDC is misconfigured. That’s its whole purpose.
If none of the above gets you unblocked, email support@radarhq.io with the three artifacts at the top of this page.