# Troubleshooting

### Collect logs

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

{% hint style="info" %}
You can share these logs with Syntho Support at <support@syntho.ai>.
{% endhint %}

### Quick triage

1. Check pods and placement:

```bash
kubectl get pods -n syntho -o wide
```

2. Check recent events:

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

3. For a failing pod:

```bash
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`.

<details>

<summary>Common causes</summary>

* Ingress class mismatch.
* TLS enabled at the Ingress, but Syntho configured for `http`.
* ImagePullSecret missing or expired.

</details>

### Ingress issues (404, 502/504, websockets)

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

NGINX often needs increased timeouts/body size.

### ImagePullBackOff / ErrImagePull

Recreate the ImagePullSecret:

```bash
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:

```yaml
imagePullSecrets:
  - name: syntho-cr-secret
```

### Pod stuck Pending

Common causes:

* Scheduling constraints.
* Not enough CPU/memory.
* PVC provisioning issues.

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

### CrashLoopBackOff

```bash
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

```bash
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:

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