> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Rollback and troubleshooting

> Roll back a failed Midaz Helm upgrade and troubleshoot common post-upgrade issues — pod crashes, schema errors, and broken integrations.

## Rollback procedures

***

If something goes wrong after an upgrade, you can rollback to a previous version.

### When to rollback

Consider rolling back if you observe:

* Pods failing to start or crash-looping
* API errors or service unavailability
* Data inconsistencies
* Performance degradation

### Check release history

View the revision history for a release:

```bash theme={null}
helm history midaz -n midaz
```

Example output:

```
REVISION  STATUS      CHART           APP VERSION  DESCRIPTION
1         superseded  midaz-4.4.8     3.4.7        Install complete
2         deployed    midaz-5.7.0     3.5.3        Upgrade complete
```

### Execute rollback

Rollback to a specific revision:

* **Rollback Midaz to previous revision**

```bash theme={null}
helm rollback midaz 1 -n midaz
```

* **Rollback plugin (example: CRM)**

```bash theme={null}
helm rollback plugin-crm 1 -n midaz
```

### Verify rollback

* **Verify release version**

```bash theme={null}
helm list -n midaz
```

* **Verify pods**

```bash theme={null}
kubectl get pods -n midaz
```

* **Check logs**

<Tabs>
  <Tab title="Ledger (v5.x)">
    ```bash theme={null}
    kubectl logs -n midaz deployment/midaz-ledger --tail=50
    ```
  </Tab>

  <Tab title="Legacy (v4.x)">
    ```bash theme={null}
    kubectl logs -n midaz deployment/midaz-onboarding --tail=50
    ```
  </Tab>
</Tabs>

<Danger>
  Rollbacks may not revert database schema changes. If the upgrade included database migrations, you may need to restore from a database backup.
</Danger>

## Troubleshooting

***

### Pods stuck in Pending state

**Symptom:** Pods remain in `Pending` status after upgrade.

**Solution:** Check for resource constraints:

* **Describe pending pod**

```bash theme={null}
kubectl describe pod <pod-name> -n midaz
```

* **Check node resources**

```bash theme={null}
kubectl top nodes
```

### Image pull errors

**Symptom:** Pods show `ImagePullBackOff` or `ErrImagePull`.

**Solution:** Verify image registry access and credentials:

* **Check pod events**

```bash theme={null}
kubectl describe pod <pod-name> -n midaz | grep -A 10 Events
```

* **Verify image exists**

```bash theme={null}
docker pull lerianstudio/midaz-ledger:3.5.3
```

### Configuration errors

**Symptom:** Pods crash with configuration-related errors in logs.

**Solution:** Compare your values with the new defaults:

* **View current values**

```bash theme={null}
helm get values midaz -n midaz
```

* **View chart defaults**

```bash theme={null}
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.7.0
```

### Database connection issues

**Symptom:** Services fail to connect to PostgreSQL or MongoDB.

**Solution:** Verify database connectivity and credentials:

* **Check database pods**

```bash theme={null}
kubectl get pods -n midaz -l app.kubernetes.io/name=postgresql
kubectl get pods -n midaz -l app.kubernetes.io/name=mongodb
```

* **Check service logs**

<Tabs>
  <Tab title="Ledger (v5.x)">
    ```bash theme={null}
    kubectl logs -n midaz deployment/midaz-ledger | grep -i database
    ```
  </Tab>

  <Tab title="Legacy (v4.x)">
    ```bash theme={null}
    kubectl logs -n midaz deployment/midaz-onboarding | grep -i database
    ```
  </Tab>
</Tabs>

## General rollback procedure

***

If you encounter issues after any upgrade:

<CodeGroup>
  ```bash Shell theme={null}
  # List release history
  helm history midaz -n midaz

  # Rollback to previous version
  helm rollback midaz <REVISION> -n midaz

  # Verify rollback
  helm list -n midaz
  kubectl get pods -n midaz
  ```
</CodeGroup>

## Related resources

***

* [Installing Midaz with Helm](/en/platform/helm/midaz/midaz-installation) - Initial installation guide
* [Helm chart version compatibility](/en/platform/helm/helm-version-compatibility) - Version mapping reference
* [Helm repository](https://github.com/LerianStudio/helm) - Source code and release notes