Skip to main content

Troubleshooting

Common issues and their solutions.

Installation Issues​

Pod Not Starting​

Symptom: Pod stays in Pending or CrashLoopBackOff

Solutions:

  1. Check pod status:

    kubectl get pods -n flux-system -l app.kubernetes.io/name=gyre

  2. Check events:

    kubectl describe pod -n flux-system -l app.kubernetes.io/name=gyre

  3. Common causes:

    • Insufficient resources (increase limits)
    • PersistentVolume not available (check storage class)
    • Image pull errors (check image tag and registry access)

Cannot Access Web UI​

Symptom: Connection refused or timeout

Solutions:

  1. Check service:

    kubectl get svc -n flux-system gyre

  2. Verify pod is running:

    kubectl get pods -n flux-system -l app.kubernetes.io/name=gyre

  3. Test port-forward:

    kubectl port-forward -n flux-system svc/gyre 3000:80

Authentication Issues​

Cannot Login​

Symptom: "Invalid credentials" error

Solutions:

  1. Read the password from the configured admin Secret (default: gyre-initial-admin-secret):

    kubectl get secret "${GYRE_ADMIN_SECRET_NAME:-gyre-initial-admin-secret}" \
      -n flux-system \
      -o jsonpath='{.data.password}' | base64 -d && echo

  2. If the password is no longer known, update the Secret. Enter a new strong password when prompted:

    read -r -s -p 'New admin password: ' new_password
    printf '\n'
    printf '%s' "$new_password" | kubectl create secret generic \
      "${GYRE_ADMIN_SECRET_NAME:-gyre-initial-admin-secret}" -n flux-system \
      --from-file=password=/dev/stdin --dry-run=client -o yaml | kubectl apply -f -
    unset new_password
    kubectl rollout restart deployment/gyre -n flux-system
    kubectl rollout status deployment/gyre -n flux-system

    Gyre keeps the current Secret password hash in memory, so restart the deployment after changing the Secret. Adjust the namespace or deployment name if your release uses different values. Never edit the database password hash directly.

For local deployments, ADMIN_PASSWORD is used only when the first local admin is created; changing it does not reset an existing account. An authenticated local admin can change their own password or reset another user's password in Gyre. There is no supported offline password reset command for a locked-out local database.

OAuth Login Fails​

Symptom: Redirect loop or "Authentication failed"

Solutions:

  1. Verify OAuth credentials:

    kubectl get secret -n flux-system | grep oauth

  2. Check callback URL is correct in OAuth provider

  3. Verify Gyre URL matches OAuth configuration

  4. Check logs:

    kubectl logs -n flux-system -l app.kubernetes.io/name=gyre | grep oauth

Cluster Connection Issues​

Cannot Connect to Cluster​

Symptom: "Cluster unavailable" or timeout

Solutions:

  1. Verify ServiceAccount permissions:

    kubectl auth can-i --list --as=system:serviceaccount:flux-system:gyre

  2. Check ClusterRoleBinding:

    kubectl get clusterrolebinding | grep gyre

  3. Test K8s API access from pod:

    kubectl exec -it -n flux-system \
      deployment/gyre -- \
      curl -k https://kubernetes.default.svc/healthz

Multi-Cluster Issues​

Symptom: Cannot see resources from other clusters

Solutions:

  1. Verify kubeconfig is valid:

    kubectl config view --raw

  2. Check cluster context exists:

    kubectl config get-contexts

  3. Test cluster connection:

    kubectl --context=other-cluster get nodes

Performance Issues​

Slow Loading​

Symptom: Pages take long to load

Solutions:

  1. Increase resources:

    resources:
      limits:
        cpu: 2000m
        memory: 1Gi

  2. Check database size:

    kubectl exec -it -n flux-system \
      deployment/gyre -- \
      ls -lh /data/gyre.db

  3. Clear cache:

    kubectl rollout restart deployment -n flux-system gyre

High Memory Usage​

Symptom: OOMKilled or high memory usage

Solutions:

  1. Check for memory leaks:

    kubectl top pod -n flux-system -l app.kubernetes.io/name=gyre

  2. Reduce cache TTL:

    config:
      dashboardCacheTtlMs: 10000 # 10 seconds

  3. Limit concurrent connections

Resource Display Issues​

Resources Not Showing​

Symptom: Empty list or "No resources found"

Solutions:

  1. Verify FluxCD is installed:

    kubectl get pods -n flux-system

  2. Check resource exists:

    kubectl get kustomizations -A

  3. Verify RBAC permissions

  4. Check logs:

    kubectl logs -n flux-system -l app.kubernetes.io/name=gyre | grep error

Wrong Status Displayed​

Symptom: Status doesn't match actual resource state

Solutions:

  1. Refresh page (hard refresh: Ctrl+Shift+R)

  2. Check SSE stream connection (/api/v1/events) in browser DevTools Network tab. Server endpoint: src/routes/api/v1/events/+server.ts, client store: src/lib/stores/events.svelte.ts.

  3. Restart Gyre pod:

    kubectl rollout restart deployment -n flux-system gyre

Database Issues​

Database Locked​

Symptom: "database is locked" errors

Solutions:

  1. Restart the pod:

    kubectl rollout restart deployment -n flux-system gyre

  2. Check disk space:

    kubectl exec -it -n flux-system \
      deployment/gyre -- \
      df -h

Data Loss​

Symptom: Users, settings, or data missing

Solutions:

  1. Check PersistentVolume:

    kubectl get pvc -n flux-system

  2. Check Gyre's Admin → Backups page for an available database backup. Restore through the application or follow the backup restore guide.

Getting Help​

If you can't resolve the issue:

  1. Check logs:

    kubectl logs -n flux-system -l app.kubernetes.io/name=gyre --tail=100

  2. Gather information:

    • Gyre version
    • Kubernetes version
    • FluxCD version
    • Browser console errors

  3. Open an issue: