Recovery from a failed upgrade
If an ITRS Analytics upgrade fails, follow these steps to diagnose the issue, retry the deployment, and escalate to support when needed.
Warning
Downgrading to an earlier version of ITRS Analytics is not supported. Recovery from a failed upgrade must proceed forward — you cannot roll back to the previous version.
Recovery procedure Copied
Collect a support bundle Copied
Collect a support bundle before you attempt any recovery actions. ITRS Support needs the failure-state bundle to diagnose the root cause. A bundle collected after recovery attempts may no longer contain the original failure evidence.
Generate a bundle from the KOTS Admin Console or the command line. For background on what a support bundle includes and when to use one, see Support bundles.
Consult the upgrade notes for your version Copied
Review the ITRS Analytics Upgrade Notes for the version you are upgrading to. That page lists known failure modes and their resolutions. Check whether your failure is covered before you retry the deployment.
Some failures have dedicated recovery steps. For example, if you see a Deploy Failed error after upgrading without Dynamic Thresholds enabled, see Recovery steps for Embedded Cluster and BYO upgrade failures.
For additional troubleshooting guidance, see the ITRS Analytics FAQ.
Redeploy Copied
After you resolve the blocker identified in the upgrade notes or related recovery guidance, return to the KOTS Admin Console Version history page and click Redeploy.
Schema upgrades are resumable: failed migration scripts continue from the failure point on re-run. Redeploying is safe and does not cause data duplication or corruption.
Contact ITRS Support if the issue persists Copied
Please contact ITRS Support if any of the following apply:
- You cannot identify the cause from the upgrade notes or FAQ.
- Redeploy continues to fail.
- The deployment appears stuck with no progress.
Warning
Do not attempt to uninstall or manually re-run the upgrade for Kafka controller or ClickHouse migration failures. Please contact ITRS Support directly for these scenarios.
For background on these upgrade paths, see Upgrading Kafka Controller Replica for HA installations and Upgrade to version 2.18.x: ClickHouse migration guide. If you are monitoring an in-progress metrics migration to ClickHouse, see Monitor metrics migration progress.
When you contact support:
- Attach the support bundle collected before recovery.
- If you attempted recovery and the failure changed, collect and attach a second bundle that captures the new state.
Helm-only installs Copied
If you deploy with Helm directly (without the KOTS Admin Console):
- Inspect release history and status:
helm history <release-name> -n <namespace> - After you fix the blocker, re-run the upgrade:
helm upgrade <release-name> <chart> -n <namespace> -f <values-file> - Collect diagnostics using the command-line support bundle method.
The same escalation criteria apply. Please contact ITRS Support for any failure you cannot resolve from the Upgrade Notes.