# Troubleshooting

### Update times out

If your `helm update` times out, you can extend the time limit from the default 5 minutes with `--timeout 1h`. Or pass the `--debug` option to get more information. For example:

```bash
helm upgrade --install --namespace "ess" ess \
    oci://registry.element.io/matrix-stack:25.4.2 \
    --values "$HOME/ess-config/element.yaml" \
    --values "$HOME/ess-config/essCredentials.yam"l \
    --values "$HOME/ess-config/hostnames.yaml" \
    --values "$HOME/ess-config/mas.yaml" \
    --values "$HOME/ess-config/postgres.yaml" \
    --values "$HOME/ess-config/rtc.yaml" \
    --values "$HOME/ess-config/tls.yaml" \
    --wait --timeout 1h --debug 2>&1 | tee ess-upgrade.log
```

### Stuck upgrade

If an upgrade failed, but is preventing you from running a new upgrade

```plaintext
Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress
```

You can use Helm to roll back. Make sure you are not rolling back to an incompatible version. For example for Synapse, see [this](https://element-hq.github.io/synapse/latest/upgrade.html#rolling-back-to-older-versions) page for compatible Synapse versions.

List Helm deployment versions
```bash
$ helm --namespace ess history ess
REVISION        UPDATED                         STATUS          CHART                   APP VERSION     DESCRIPTION                                                                                                                                                                   
6               Tue Mar 25 13:17:00 2025        superseded      matrix-stack-0.7.5                      Upgrade complete                                                                                                                                                              
7               Mon Mar 31 13:00:49 2025        superseded      matrix-stack-0.8.1                      Upgrade complete                                                                                                                                                              
8               Tue Apr  8 10:49:10 2025        superseded      matrix-stack-0.9.1                      Upgrade complete                                                                                                                                                              
9               Fri May  2 11:31:29 2025        failed          matrix-stack-0.11.3                     Upgrade "ess" failed: failed to create resource: Service "ess-matrix-rtc-sfu-tcp" is invalid: spec.ports[0].nodePort: Invalid value: 30881: provided port is already allocated
10              Fri May  2 11:38:15 2025        superseded      matrix-stack-0.11.3                     Upgrade complete                                                                                                                                                              
11              Tue May  6 15:51:44 2025        superseded      matrix-stack-0.11.4                     Upgrade complete                                                                                                                                                              
12              Thu May  8 12:55:26 2025        superseded      matrix-stack-0.11.5                     Upgrade complete                                                                                                                                                              
13              Fri May 16 09:22:36 2025        deployed        matrix-stack-0.12.0                     Upgrade complete                                                                                                                                                              
14              Wed May 21 14:47:23 2025        failed          matrix-stack-25.4.2                     Upgrade "ess" failed: pre-upgrade hooks failed: 1 error occurred:                                                                                                             
                                                                                                                * timed out waiting for the condition                                                                                                                                         
                                                                                                                                                                                                                                                                                      
                                                                                                                                                                                                                                                                                      
15              Wed May 21 14:55:14 2025        pending-upgrade matrix-stack-25.4.2                     Preparing upgrade 
```

Roll back to the last good deployment

```bash
$ helm --namespace ess rollback ess 13
Rollback was a success! Happy Helming!
```

You can now run the normal `helm upgrade --install ...` command again.