Troubleshooting

This guide helps you diagnose and resolve common issues when running Scalekit on your own Kubernetes cluster. Start with the quick diagnostics, then use the symptom/cause/solution sections below to fix specific problems.

Quick diagnostics

Before investigating specific errors, run these basic checks to identify which pods are unhealthy and gather initial diagnostics.

Check pod status

Set the namespace (the setup script defaults to scalekit):

# Set once for your deployment
NAMESPACE=${NAMESPACE:-scalekit}

kubectl get pods -n ${NAMESPACE}
kubectl describe pod <pod-name> -n ${NAMESPACE}
kubectl logs <pod-name> -n ${NAMESPACE} --tail=100

For the main Scalekit pod (multiple containers), specify the container:

# Main auth service
kubectl logs <pod-name> -n ${NAMESPACE} -c scalekit --tail=100

# Dashboard
kubectl logs <pod-name> -n ${NAMESPACE} -c dashboard --tail=100

# Svix (webhooks)
kubectl logs <pod-name> -n ${NAMESPACE} -c svix --tail=100

Useful kubectl flags

• Add --previous to see logs from the last crashed container.
• Use kubectl get events -n ${NAMESPACE} --sort-by=.lastTimestamp for recent cluster events.

Helm deployment issues

ImagePullBackOff or ErrImagePull

Symptom: Pods fail to start with ImagePullBackOff or ErrImagePull.

Cause: The cluster cannot pull images from the Scalekit container registry. This is almost always caused by a missing or expired registry secret.

Solution:

1. Confirm the secret exists:

   kubectl get secret artifact-registry-secret -n ${NAMESPACE}

2. If it is missing, recreate it:

   kubectl create secret docker-registry artifact-registry-secret \
     --docker-server=<registry-server-url> \
     --docker-username=oauth2accesstoken \
     --docker-password=<your-registry-token> \
     -n ${NAMESPACE}

3. Verify your registry token has not expired. Tokens from the distribution portal are time-limited.

Token expiry breaks image pulls

When the token expires, new deployments and upgrades will fail with ImagePullBackOff. Set a reminder to renew it before it lapses.

Migration hook fails or times out

Symptom: The db-migrations job fails or the Helm install hangs on the pre-install hook.

Cause: The migration job cannot connect to PostgreSQL (wrong connection string, database does not exist, or network issue).

Solution:

1. Check the job logs:

   kubectl get jobs -n ${NAMESPACE}
   kubectl logs job/scalekit-db-migrations -n ${NAMESPACE}

2. Verify the DATABASE_URL secret is correct and points to a reachable PostgreSQL instance.

3. Ensure the target databases (scalekit, webhooks, openfga) exist and the database user has full privileges.

Database creation

The setup script prints the exact CREATE DATABASE commands. Run them on your PostgreSQL server if the databases are missing.

Pod stuck in CrashLoopBackOff

Symptom: The main Scalekit pod keeps crashing and restarting.

Cause: A required secret is missing or a configuration value (hostnames, domains, credentials) is incorrect.

Solution:

1. Check the previous container logs for the exact error:

   kubectl logs <pod-name> -n ${NAMESPACE} -c scalekit --previous

2. Common causes:

   • Missing keys in authentication-secret → Re-run bash setup-secrets.sh
   • database.host or redis.host unreachable → Verify connectivity and values in values.yaml
   • domain does not match your gateway hostname → Correct values.yaml and re-apply

3. Once the cause is fixed, delete the pod (or the whole release) so Kubernetes restarts it with the updated configuration.

Gateway and ingress issues

Gateway has no external IP

Symptom: kubectl get gateway shows no address or the Gateway stays in a pending state.

Cause: The GatewayClass is missing, or the Gateway controller (e.g. GKE Gateway) is not running in the cluster.

Solution:

1. Inspect the Gateway:

   kubectl get gateway -n ${NAMESPACE}
   kubectl describe gateway scalekit -n ${NAMESPACE}

2. Verify a matching GatewayClass exists:

   kubectl get gatewayclass

3. Ensure gateway.className in your values.yaml exactly matches the installed GatewayClass name.

GKE-specific

On GKE, you must enable the GKE Gateway controller in your cluster settings before using Gateway API resources.

Getting help

If the issue is not covered here, gather the following information before contacting support:

• Namespace: The Kubernetes namespace where Scalekit is deployed
• Error messages: Full output from kubectl logs, kubectl describe, and Helm output
• Pod status: Output of kubectl get pods -n ${NAMESPACE}
• Values used: Relevant sections from your values.yaml (redact secrets)
• Steps to reproduce: What you were doing when the issue occurred
• Environment: Local (Minikube), GKE, or other cluster

Support channels

• Documentation: Review the quickstart, installation, and configuration guides
• Community: Join the #ask-anything channel on Slack (the Scalekit Community workspace)
• Support: Submit a ticket through your Scalekit dashboard or contact support@scalekit.com for production issues

Next steps

• Upgrades and maintenance
• Configuration reference