Configuration file fails schema validation

What this failure means

A configuration file exists but fails validation because a required field is missing, an unrecognized field is present, or a value does not match the expected type or constraint. The tool or framework rejects the config and the CI step fails immediately.

Symptoms

Faultline looks for one or more of these log fragments:

schema validation failed
invalid configuration
config.*invalid
unknown field
unexpected field
required field.*missing
field.*is required
invalid value

Diagnosis

Config schema failures arise from:

1. A tool upgrade that added required fields or removed deprecated ones
2. A copy-paste error introducing a typo in a field name
3. A wrong type (string where integer expected, list where scalar expected)
4. Merging from a template without removing example-only placeholders
5. YAML indentation error that changes the structure

Identify the exact invalid portion from the error:

# Validate YAML syntax
python3 -c "import yaml, sys; yaml.safe_load(open(sys.argv[1]))" config.yaml

# Validate JSON
python3 -m json.tool config.json

# Validate against a schema if available
npx ajv validate -s schema.json -d config.json

Fix steps

1. Read the full validation error, which usually names the invalid field and its location (e.g., .database.port: expected integer, got string).

2. Compare the failing config against the tool’s current documentation or upgrade changelog to identify renamed, removed, or newly required fields.

3. Fix the specific field:

   • Remove unrecognized keys or rename them to the current field names
   • Correct the type (quote/unquote values as needed in YAML)
   • Add required fields with appropriate values

4. For YAML: indent with spaces (never tabs), validate with a linter:

   yamllint config.yaml
   

5. For tool-specific config formats, use the tool’s own validation command:

   helm lint .          # Helm charts
   terraform validate   # Terraform
   docker compose config  # Compose files
   ansible-lint         # Ansible
   

6. Pin the tool version so config schema changes do not break unexpectedly:

   # package.json
   "eslint": "8.57.0"  # not "^8" or "latest"
   

Validation

• Run the tool’s validation command (--dry-run, validate, lint) and confirm it exits 0.
• Re-run the failing CI step.

Why it matters

Config schema failures block the entire pipeline immediately. Unlike build errors that occur mid-compilation, schema validation errors prevent any useful work from starting, wasting runner time on a fixable configuration issue.

Prevention

• Add config validation as the first step, before expensive ones.
• Use IDE plugins that validate config schemas in real time.
• Commit config file changes with tool-version context in the commit message.
• Pin tool versions to prevent upgrade-driven schema drift.

How Faultline detects it

Use faultline explain invalid-config-schema to see the full playbook.

faultline analyze build.log
faultline explain invalid-config-schema

Generated from playbooks/bundled/log/build/invalid-config-schema.yaml. Do not edit directly.