Helm Charts Troubleshooting¶

For the shared debugging workflow, start with Debugging and Troubleshooting. It explains Debug Events, instance debug, and the relationship between workflow state and live resource state.

Helm Troubleshooting Checklist¶

If a Helm-based deployment fails or stays in a provisioning state, start from Debug Events to identify the failed stage and resource. Then inspect the Helm resource with:

omnistrate-ctl instance debug <instance-id>

Use the instance debug output to investigate:

1. Whether the rendered chart values match the API parameters, system parameters, and chart defaults you expected.
2. Helm client logs for template rendering errors, hook failures, timeout messages, or Kubernetes API validation errors.
3. Kubernetes resources created by the chart, especially Jobs, hooks, Services, load balancers, readiness probes, and pending pods.
4. Leftover CRDs, finalizers, or namespaced resources if create, upgrade, or delete workflows repeatedly fail.
5. Runtime settings such as wait, waitForJobs, disableHooks, skipCRDs, upgradeCRDs, and timeoutNanos if the release lifecycle does not match the chart behavior.

The shared Helm Troubleshooting Checklist contains the same checks alongside the other deployment strategies.

If you change chart values, API parameter mappings, chart source, or other rendered artifacts, publish a new Plan version and trigger a fresh workflow instead of repeatedly restarting the same failed workflow. For runtime flag details, see Helm Runtime Configuration.