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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-kubernetes/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.