Introduction

Helm charts can declare dependencies on other charts with semantic version constraints. When the dependency resolution cannot find a version that satisfies all constraints -- due to conflicting version requirements, missing repository entries, or unavailable chart versions -- Helm aborts the installation. This is common when charts depend on multiple sub-charts with overlapping but incompatible version requirements.

Symptoms

  • helm install or helm dependency update fails with version constraint error
  • Error message indicates which dependency cannot be satisfied
  • Chart works locally but fails in CI/CD pipeline with different repository state
  • helm dependency build reports no matching version for a dependency
  • Error message: Chart.yaml: dependency "redis" has an invalid version/constraint format

Common Causes

  • Dependency version pinned to a specific version that is no longer available in the repository
  • Two chart dependencies requiring incompatible versions of a shared sub-chart
  • Chart repository not added to Helm's repository list
  • Semver constraint syntax error in Chart.yaml (e.g., >=1.0 <2.0 vs >=1.0,<2.0)
  • Chart.lock file out of sync with Chart.yaml dependency declarations

Step-by-Step Fix

  1. 1.Check the dependency resolution error details: Identify the failing dependency.
  2. 2.```bash
  3. 3.helm dependency update ./chart
  4. 4.# Look for: "can't get a valid version of X"
  5. 5.`
  6. 6.Verify the chart repository contains the required version: Check available versions.
  7. 7.```bash
  8. 8.helm repo update
  9. 9.helm search repo redis --versions | head -20
  10. 10.`
  11. 11.Update the version constraint in Chart.yaml: Adjust to an available version.
  12. 12.```yaml
  13. 13.# Chart.yaml
  14. 14.dependencies:
  15. 15.- name: redis
  16. 16.version: ">=17.0.0 <18.0.0"
  17. 17.repository: "https://charts.bitnami.com/bitnami"
  18. 18.`
  19. 19.Resolve version conflicts between dependencies: Align sub-chart versions.
  20. 20.```yaml
  21. 21.# If two dependencies require different redis versions,
  22. 22.# specify a version range that satisfies both
  23. 23.dependencies:
  24. 24.- name: redis
  25. 25.version: "17.15.0" # Pin to specific version
  26. 26.repository: "https://charts.bitnami.com/bitnami"
  27. 27.`
  28. 28.Rebuild the dependency lock file: Update Chart.lock.
  29. 29.```bash
  30. 30.helm dependency update ./chart
  31. 31.helm dependency build ./chart
  32. 32.# Verify
  33. 33.cat ./chart/Chart.lock
  34. 34.`

Prevention

  • Pin dependency versions to specific versions rather than ranges in production charts
  • Run helm dependency update and commit the updated Chart.lock to version control
  • Use private chart repositories (Harbor, ChartMuseum) to ensure dependency availability
  • Test chart dependency resolution in CI/CD pipelines before deployment
  • Monitor upstream chart repositories for version changes and deprecations
  • Document the full dependency tree for each chart in the chart's README