Skip to content

air: Name the YAML path in unknown config field errors - #7528

Open
abdulkareem-db wants to merge 4 commits into
mainfrom
abdulkareem/air-friendly-unknown-config-fields
Open

abdulkareem-db wants to merge 4 commits into
mainfrom
abdulkareem/air-friendly-unknown-config-fields

Conversation

@abdulkareem-db

Copy link
Copy Markdown

Changes

Unknown or misspelled keys in an air run workload YAML now produce an error that names the YAML path and line, suggests the closest valid field, lists the valid fields at that level, and points at the matching -h config.<path> help. When a key has no close match, the error also says it may come from newer documentation than this CLI version supports.

Before:

Error: invalid config workload.yaml: yaml: unmarshal errors:
  line 6: field rot_path not found in type aircmd.codeSourceConfig

After:

Error: invalid config workload.yaml: line 6: unknown field "code_source.rot_path"; did you mean "root_path"?
fields under "config.code_source" are: git, include_paths, remote_volume, root_path
run "databricks air run -h config.code_source" for details

No close match:

Error: invalid config workload.yaml: line 7: unknown field "code_source.fancy_new_option"
fields under "config.code_source" are: git, include_paths, remote_volume, root_path
run "databricks air run -h config.code_source" for details

fields from newer documentation may not be supported by this CLI (version X.Y.Z); update the Databricks CLI (run 'databricks version --check')

Why

The go-yaml error exposes internal Go type names (aircmd.runConfig, aircmd.codeSourceConfig) and gives no path or suggestion. A common way to hit it is running a current workload YAML on an older CLI. For example, the flat code_source.root_path form is rejected by CLIs before v1.20.0 and nothing in the error suggests upgrading.

The check walks the parsed YAML against configSchema(), the same schema that --override path validation and -h config use. It reuses findConfigChild and closestConfigField, so hidden and legacy fields (code_source.type, code_source.snapshot) and inline fields are handled the same way. All unknown keys are reported, not just the first. KnownFields(true) stays as a backstop. --override errors are unchanged.

Tests

  • Unit tests in cmd/air/runconfig_test.go: a top-level typo, a nested typo, an unknown key with no close match (version hint), several unknown keys reported together, line numbers, and hidden legacy keys still loading.
  • go test ./cmd/air/... passes.
  • Manually, with a built binary and air run --dry-run: the three error cases above, and an unchanged valid workload config still validates.

This pull request and its description were written by Isaac.

abdulkareem-db and others added 2 commits November 11, 2026 22:29
Unknown or misspelled keys in an `air run` workload YAML surfaced the raw
go-yaml error, which names internal Go types (e.g. "field rot_path not found
in type aircmd.codeSourceConfig") and gives no path or suggestion.

Walk the parsed YAML against configSchema() before decoding and report every
unknown key with its line, dotted YAML path, a did-you-mean suggestion, the
valid sibling fields, and the matching `-h config.<path>` pointer. When a key
has no close match, note that it may come from newer documentation than the
running CLI version supports. KnownFields(true) stays as a backstop.

Fixes CNXT-2566 and CNXT-2554.

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
@github-actions github-actions Bot added the AIR Databricks AI Runtime CLI label Nov 12, 2026
@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 7879917

Run: 43130013891

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 270 15 6:20
💚​ aws-windows-latest-4core-16gb 1 272 13 4:05
💚​ azure linux-2core-8gb 1 269 15 5:28
💚​ azure-windows-latest-4core-16gb 1 271 13 3:52
💚​ gcp linux-2core-8gb 1 270 15 7:28
💚​ gcp-windows-latest-4core-16gb 1 272 13 4:51
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 6 slowest tests (at least 2 minutes):
duration env testname
4:12 gcp linux-2core-8gb TestAccept
4:03 aws linux-2core-8gb TestAccept
4:00 azure linux-2core-8gb TestAccept
3:47 azure-windows-latest-4core-16gb TestAccept
3:42 gcp-windows-latest-4core-16gb TestAccept
3:22 aws-windows-latest-4core-16gb TestAccept

…-field check

Unknown keys inside an --override value were reported with the override
string's line number as if they came from the config file. Validate each
override value against its target schema field before splicing it in, and
report it in the --override error voice.

Only walk YAML sequences for list-typed fields (and mappings for non-list
fields), so a shape mismatch such as a list document or `compute: [...]`
surfaces the decoder's type error instead of "unknown field" plus the
update-CLI hint. Merge keys with a list of sources are still walked.

Hedge the newer-CLI hint, since some unknown keys (priority, _bases_) are
intentionally unsupported, and extract visibleConfigChildNames for the three
places that listed documented sibling fields.

Co-authored-by: Isaac <no-reply@databricks.com>

@pietern pietern left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@abdulkareem-db Please check out how we use libs/dyn for bundles. It implements the same thing and includes line/col information for every element in the object.

@pardis-beikzadeh-db pardis-beikzadeh-db left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Crash: collectUnknownConfigKeys runs before the decoder and doesn't track the aliases it has already visited. A mapping that merges its own anchor crashes air run with a Go stack overflow:

experiment_name: x
compute:
  accelerator_type: GPU_1xA10
  num_accelerators: 1
command: python t.py
code_source: &c
  root_path: src
  <<: *c
runtime: goroutine stack exceeds 1000000000-byte limit
fatal error: stack overflow

On main the same file fails cleanly with yaml: anchor 'c' value contains itself. Nested merges also skip the decoder's alias limit. With 6 levels of 10 merges each, this PR reports 1,000,001 unknown fields in about 2s, where main rejects the file with excessive aliasing. Running the decoder first, or keeping a set of visited alias nodes, would fix both.

+1 to pietern's libs/dyn comment. One thing to know: dyn reads json tags, and the air config structs only have yaml tags.

Nits:

  • runconfig_load.go:174 only checks whether the direct parent is hidden. For a key under code_source.snapshot.git, the error says to run databricks air run -h config.code_source.snapshot.git, and that command fails with unknown config field "config.code_source.snapshot".
  • A single error names the field as "code_source.rot_path" and then as "config.code_source". With this PR there are three wordings for an unknown field (-h, the file check, and the --override path). Could this reuse unknownConfigFieldError?
  • runconfig_test.go:379: no code prints update the Databricks CLI, so this deny check can never fail. Should it check for newer documentation instead?
  • The description still says "--override errors are unchanged", but the last commit checks override values. Its "No close match" sample also doesn't match the hint text the code prints.

@pardis-beikzadeh-db

Copy link
Copy Markdown
Contributor

Heads-up: #7574 (Dima) adds the same unknown-config-field explanation and conflicts with this PR in all four files. Let's land only one; please sort out with @dimk0 which.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AIR Databricks AI Runtime CLI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants