Helm "values don't meet the specifications of the schema" in CI

By Daniel Zoghalchali·Latchkey

A chart can ship values.schema.json to validate user values. When supplied values violate the schema - wrong type, missing required key, bad enum - Helm fails fast before templating.

What this error means

A helm install/upgrade step fails with "values don't meet the specifications of the schema", listing the offending value paths and what the schema expected.

Error: values don't meet the specifications of the schema(s) in the
following chart(s):
api:
- replicaCount: Invalid type. Expected: integer, given: string
- image.repository is required

Common causes

Wrong value type

A value provided as a string where the schema expects an integer/boolean (a common CI templating artifact).

Missing required value

A required key in the schema was not supplied.

Value outside allowed set

A value violates an enum or range in the schema.

How to fix it

Correct values to match the schema

Fix the named paths: types, required keys, and allowed values.

helm install api ./chart -f values.yaml --dry-run --debug

Avoid stringified numbers from CI

1. When injecting values via --set, ensure numbers/booleans are not quoted into strings.
2. Use --set-json for typed values where needed.
3. Provide all required keys the schema declares.

How to prevent it

• Validate values with --dry-run in CI before deploy.
• Keep a values file under version control that satisfies the schema.
• Use --set-json for typed overrides to avoid string coercion.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation