Troubleshooting

Collect logs

kubectl -n syntho logs deployment/core >> core.log
kubectl -n syntho logs deployment/backend >> backend.log
kubectl -n syntho logs deployment/frontend >> frontend.log

You can share these logs with Syntho Support at [email protected].

Quick triage

1. Check pods and placement:

kubectl get pods -n syntho -o wide

1. Check recent events:

kubectl get events -n syntho --sort-by=.lastTimestamp | tail -n 50

1. For a failing pod:

kubectl describe pod -n syntho <pod-name>
kubectl logs -n syntho <pod-name>
kubectl logs -n syntho <pod-name> -p

UI not accessible

• Check Ingress address and DNS.

• Check pods: kubectl get pods -n syntho.

Common causes

• Ingress class mismatch.

• TLS enabled at the Ingress, but Syntho configured for http.

• ImagePullSecret missing or expired.

Ingress issues (404, 502/504, websockets)

kubectl get ingress -n syntho
kubectl describe ingress -n syntho <ingress-name>

NGINX often needs increased timeouts/body size.

ImagePullBackOff / ErrImagePull

Recreate the ImagePullSecret:

kubectl delete secret syntho-cr-secret -n syntho
kubectl create secret docker-registry syntho-cr-secret \
  --namespace syntho \
  --docker-server=<REGISTRY_HOST> \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD>

Ensure both charts reference it:

imagePullSecrets:
  - name: syntho-cr-secret

Pod stuck Pending

Common causes:

• Scheduling constraints.

• Not enough CPU/memory.

• PVC provisioning issues.

kubectl describe pod -n syntho <pod-name>
kubectl get pvc -n syntho

CrashLoopBackOff

kubectl logs -n syntho <pod-name>
kubectl logs -n syntho <pod-name> -p

Common causes:

• Wrong external PostgreSQL/Redis credentials or network access.

• Missing required secret values.

• Encryption/secret key changed after first startup.

Database connectivity (external PostgreSQL)

Checks:

• Network policies allow egress to PostgreSQL.

• DNS resolves the PostgreSQL hostname from the namespace.

• User has permissions for schema migrations.

Ray not Ready / jobs not running

kubectl get svc -n syntho | grep ray

Checks:

• ray_address matches the Ray head service name.

• Ray pods can fail on volume permissions.

Collect Helm details

Also useful when reporting issues:

helm list -n syntho
helm get values syntho-ui -n syntho
helm get values ray-cluster -n syntho