Helm Install Upgrade Failure Correction Prompt

Use this prompt when a helm install or helm upgrade command fails with a non-trivial error that cannot be resolved by simply re-running the command. The ideal user is a release engineer or platform operator who has access to the failed release's current values, the chart's metadata, and the exact error message from the Helm CLI or Kubernetes API server. The prompt is designed for situations where the root cause is a configuration mismatch—such as a deprecated API version, an invalid value type, a missing required field, or a schema validation error—rather than a transient network issue or cluster resource exhaustion. It is most effective when integrated into a CI/CD retry stage, an SRE runbook automation, or a deployment operator that can capture the failure context and present a correction proposal for human review before re-applying.

Before invoking this prompt, you must collect three concrete inputs: the exact helm command that failed, the full error output (including any Kubernetes API server error messages), and the current values.yaml or --set overrides applied to the release. The prompt works by diffing the provided values against the chart's expected schema and the error context to isolate only the keys that need to change. This diff-aware approach minimizes the risk of introducing unrelated configuration drift. The output is a corrected YAML snippet that can be applied as a minimal override, not a full replacement of the existing values file. This makes it safe to use in production pipelines where you want to preserve all other intentional customizations.

Do not use this prompt when the failure is caused by a corrupted Helm release state, a broken tiller (in Helm v2), or a cluster-wide outage. It is also inappropriate for failures that require manual intervention, such as resolving a Pending PersistentVolumeClaim that needs a storage class administrator to provision a volume. The prompt does not have access to live cluster state beyond what you provide in the error message, so it cannot diagnose issues like network policy blocks, node selector mismatches, or taint/toleration conflicts unless those are explicitly surfaced in the error output. For those scenarios, use the Kubernetes Manifest Apply Failure Retry Prompt or the Node Scheduling Failure Recovery Prompt instead. After receiving the correction proposal, always review the diff before applying it, and run a helm template or --dry-run to validate the fix against the target cluster's API version schema.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a release engineer, consuming the failed release's context—its values, chart metadata, and the exact error message—to produce a corrected values.yaml override. The output is structured to isolate only the changed values, making it easy to review and apply the fix without scanning the entire configuration. Before using this prompt, ensure you have captured the full error output from helm install or helm upgrade, the chart's default values.yaml, and any custom overrides you applied. The prompt is most effective when the failure is due to a configuration mismatch, such as an invalid Kubernetes resource definition, a missing required field, or a type error in the values file. It is not suitable for diagnosing network connectivity issues, cluster-level permission errors, or Helm client version bugs.

textCopy
You are a senior release engineer diagnosing a failed Helm operation. Your task is to analyze the provided error, the chart's default values, and the user's custom overrides to produce a corrected `values.yaml` override file.

## Inputs
- [HELM_ERROR_OUTPUT]: The full error message from the `helm install` or `helm upgrade` command.
- [CHART_DEFAULT_VALUES]: The complete default `values.yaml` content for the chart.
- [USER_OVERRIDE_VALUES]: The custom `values.yaml` overrides that were applied during the failed operation.
- [CHART_METADATA]: The chart name, version, and any relevant dependency information.

## Instructions
1.  **Analyze the Error:** Parse [HELM_ERROR_OUTPUT] to identify the specific Kubernetes resource (e.g., Deployment, Service, ConfigMap) and the field that caused the failure.
2.  **Trace the Source:** Cross-reference the error with [CHART_DEFAULT_VALUES] and [USER_OVERRIDE_VALUES] to determine if the root cause is a missing required value, a type mismatch, or an invalid configuration in the user's overrides.
3.  **Generate a Correction:** Produce a corrected `values.yaml` block that resolves the error. This block must be a valid YAML snippet.
4.  **Isolate the Diff:** Your output must contain *only* the YAML keys and values that need to be changed or added. Do not output the entire values file. The goal is a minimal, targeted fix.
5.  **Explain the Fix:** After the YAML block, provide a concise, step-by-step explanation of what was wrong and how your correction resolves it.

## Output Format
Your response must follow this structure exactly:

### Corrected Values Override
```yaml
# Only the changed or added values
[KEY_PATH]: [CORRECTED_VALUE]

Explanation

1. [Step 1 of the diagnosis and fix]
2. [Step 2 of the diagnosis and fix]

Constraints

• Do not invent new configuration values that are not implied by the chart's schema or the error message.
• If the error is ambiguous, state the most likely cause and suggest diagnostic commands to run.
• Preserve the original intent of [USER_OVERRIDE_VALUES] wherever possible.
• The YAML output must be syntactically valid and use consistent indentation.

To adapt this template, replace each square-bracket placeholder with live data from your CI/CD pipeline or terminal. For [HELM_ERROR_OUTPUT], capture the raw stderr from the failed command. For [CHART_DEFAULT_VALUES], you can often retrieve this with helm show values <chart-name>. The [USER_OVERRIDE_VALUES] should be the exact file or --set strings you provided. The model's output is designed to be piped directly into a new values-fix.yaml file. Before applying the fix, always perform a helm template or --dry-run to validate the corrected output against the target cluster's API version schema. This prompt is a recovery tool, not a replacement for a full CI/CD validation gate.

This prompt is designed to sit inside a release pipeline or operator loop, not a chat window. The typical integration point is after helm upgrade --install exits with a non-zero status. Capture the full error output, the current values.yaml (or the merged user-supplied overrides), and the chart metadata (name, version, repository) before calling the model. The prompt expects these three inputs as structured context, not as a free-text dump. If you are using a GitOps tool like Flux or ArgoCD, extract the failed release's manifest and values from the controller logs rather than from the Helm CLI directly.

Validation before retry. The model output must be treated as a proposed values.yaml override block, not a direct apply. Before running helm upgrade again, validate that: (1) the output is valid YAML, (2) it contains only the keys that changed relative to the original values, (3) no required keys were dropped, and (4) the chart's values.schema.json (if present) accepts the corrected block. A diff-aware harness should compute the delta between the original and corrected values and surface only the changed sections to the operator. For high-risk releases, require a human to approve the diff before the retry is submitted.

Retry budget and escalation. Wrap the prompt call in a retry loop with a hard limit—two correction attempts is a reasonable default. If the second helm upgrade also fails, capture the new error and feed it back to the model with the prior correction attempt included as context. If the third attempt fails, stop retrying and escalate to the on-call channel with the full failure history, the proposed diffs, and a link to the release. Log every correction attempt with the model's reasoning, the diff, and the validation result so that postmortems can distinguish between a prompt failure and an underlying chart or cluster issue.

Model choice and tool use. This workflow benefits from a model with strong YAML and structured diff capabilities. If your platform supports tool use, provide a validate_helm_values tool that runs helm lint and helm template --dry-run against the proposed values, returning any errors to the model as feedback before the final output is produced. This turns the prompt into a self-correcting loop: the model proposes a fix, the tool validates it, and the model refines the output based on the validation errors. For air-gapped or private deployments, a local model fine-tuned on Helm error patterns can replace the general-purpose model, but the validation harness must remain identical.

Observability and audit. Emit structured logs for every correction attempt: release name, namespace, chart version, original error, model output, validation result, diff, and whether the retry succeeded. These logs feed into your existing observability stack and make it possible to measure correction accuracy over time. If you detect a pattern of repeated failures for a specific chart or error type, that is a signal to improve the prompt's few-shot examples or to add a pre-flight validation step earlier in the pipeline.