Skip to content

[CNXT-2554] air: explain unknown workload YAML keys - #7574

Open
dimk0 wants to merge 5 commits into
mainfrom
air-unknown-config-field-error
Open

dimk0 wants to merge 5 commits into
mainfrom
air-unknown-config-field-error

Conversation

@dimk0

@dimk0 dimk0 commented Nov 12, 2026

Copy link
Copy Markdown
Member

Changes

An unknown key in an AIR workload YAML is now reported by its field path, with the closest valid field and the help page that lists the fields.

Before:

Error: invalid config bad.yaml: yaml: unmarshal errors:
  line 6: field enviroment not found in type aircmd.runConfig

After:

Error: invalid config bad.yaml: line 6: unknown field "enviroment"; did you mean "environment"? Run "databricks air run -h config" for the list of fields
  • Nested keys show the dotted path and point at the parent's help page, e.g. unknown field "compute.acclerator_type"; did you mean "accelerator_type"? Run "databricks air run -h config.compute" ....
  • With no close match the suggestion is omitted and the help pointer stays.
  • Several unknown keys are each reported on their own line.

loadRunConfig now checks the parsed document's keys against configSchema() (the same schema walk behind -h config.<field> and --override validation) before the strict decode. The strict decode stays in place, so nothing that was rejected before is accepted now. Keys under free-form maps (parameters, env_variables, secrets) are not checked, as before.

visibleConfigChildNames replaces two copies of the "sorted documented children" loop.

Why

CNXT-2554: the Go struct name means nothing to someone writing a workload YAML, and the old message gave no hint at the valid field.

Tests

  • Unit tests in cmd/air/runconfig_test.go for top-level, nested, list/hidden-parent, no-match, multiple-key, and free-form-map cases. Three existing assertions that pinned the old field X not found wording now pin the new message.
  • New acceptance case in acceptance/air/run with the ticket's repro.
  • go test ./cmd/air, go test ./acceptance -run 'TestAccept/air/', ./task lint-q, and ./task ws pass locally.

This pull request and its description were written by Isaac.

An unknown key in the workload YAML was reported by the strict YAML
decode, whose message names the Go struct ("field enviroment not found
in type aircmd.runConfig") and offers no hint.

Check the document's keys against the run config schema before decoding
and report each unknown key by its dotted path, with the closest valid
sibling and the `-h config` page that lists the fields.

Co-authored-by: Isaac <no-reply@databricks.com>
@dimk0
dimk0 requested review from a team as code owners November 12, 2026 20:23
@dimk0
dimk0 requested a review from rugpanov November 12, 2026 20:23
Co-authored-by: Isaac <no-reply@databricks.com>
@github-actions github-actions Bot added the AIR Databricks AI Runtime CLI label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Commit: 9208ba8b8 | Workflow run

Regression test report

Selected 1 changed tests (limit=20, 0 not selected)

1 tests: regression=1 unreleased=0 coverage=0 failing=0
test branch main (532408b) latest (v1.26.0)
TestAccept/air/run ✅ ❌ ❌
TestAccept/air/run: branch ✅ | main (532408b) ❌ | latest (v1.26.0) ❌

main (532408b):

acceptance_test.go:1374: Diff:
        --- air/run/output.txt
        +++ /tmp/TestAcceptairrun3929512762/002/output.txt
        @@ -88,7 +88,8 @@
         === unknown field suggests the near match
         
         >>> [CLI] air run -f unknown-field.yaml --dry-run
        -Error: invalid config unknown-field.yaml: line 6: unknown field "enviroment"; did you mean "environment"? Run "databricks air run -h config" for the list of fields
        +Error: invalid config unknown-field.yaml: yaml: unmarshal errors:
        +  line 6: field enviroment not found in type aircmd.runConfig
         
         Tip: use the --debug flag to see more details and a trace of this error:
           databricks --debug air run …
        
FAIL

latest (v1.26.0):

acceptance_test.go:1374: Diff:
        --- air/run/output.txt
        +++ /tmp/TestAcceptairrun1798694515/002/output.txt
        @@ -52,19 +52,13 @@
         === code_source config passes validation and reports the selected files
         
         >>> [CLI] air run -f with-code-source.yaml --dry-run
        -Dry run: code_source snapshot would include 1 file(s).
         Dry run: configuration for "smoke-test" is valid; not submitting.
         
         === git-ignored root_path is rejected instead of selecting no files
         
         >>> [CLI] air run -f ignored-root.yaml --dry-run
        -Error: code_source snapshot of [TEST_TMP_DIR]/.scratch/proj contains no files; refusing to upload an empty snapshot: root_path is ignored by git (.gitignore:1:.scratch/), and the snapshot only includes files git does not ignore. Move the project out of the ignored directory, un-ignore it, or change code_source.root_path. Inspect the rule with `git -C [TEST_TMP_DIR]/.scratch/proj check-ignore -v .`
        +Dry run: configuration for "smoke-test" is valid; not submitting.
         
        -Tip: use the --debug flag to see more details and a trace of this error:
        -  databricks --debug air run …
        -
        -Exit code: 1
        -
         === git.remote is rejected
         
         >>> [CLI] air run -f git-remote.yaml --dry-run
        @@ -88,7 +76,8 @@
         === unknown field suggests the near match
         
         >>> [CLI] air run -f unknown-field.yaml --dry-run
        -Error: invalid config unknown-field.yaml: line 6: unknown field "enviroment"; did you mean "environment"? Run "databricks air run -h config" for the list of fields
        +Error: invalid config unknown-field.yaml: yaml: unmarshal errors:
        +  line 6: field enviroment not found in type aircmd.runConfig
         
         Tip: use the --debug flag to see more details and a trace of this error:
           databricks --debug air run …
        
FAIL

@eng-dev-ecosystem-bot

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

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 9208ba8

Run: 43383240798

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 270 16 5:24
💚​ aws-windows-latest-4core-16gb 1 272 14 4:19
💚​ azure linux-2core-8gb 1 269 16 5:19
💚​ azure-windows-latest-4core-16gb 1 271 14 4:08
💚​ gcp linux-2core-8gb 1 270 16 5:13
💚​ gcp-windows-latest-4core-16gb 1 272 14 4:20
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:14 aws-windows-latest-4core-16gb TestAccept
4:13 gcp-windows-latest-4core-16gb TestAccept
3:57 azure-windows-latest-4core-16gb TestAccept
3:44 gcp linux-2core-8gb TestAccept
3:28 aws linux-2core-8gb TestAccept
3:26 azure linux-2core-8gb TestAccept

@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.

This duplicates #7528: same feature, and the two conflict in all four files, so only one should land. Please sort out with @abdulkareem-db which one.

If it's this one, it needs one fix first (inline): a self-referencing list crashes the CLI with a stack overflow instead of an error.

Comment thread cmd/air/runconfig_load.go Resolved
Comment thread cmd/air/runconfig_load.go Resolved
Comment thread cmd/air/runconfig_test.go Resolved
Following an alias that points at its own ancestor recursed until the
stack overflowed. Also keep the help pointer at the nearest documented
field for keys below a hidden one.

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

dimk0 commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

Re the review: the self-referencing-list crash and the two other inline points are fixed in 92fbf89 (threads answered).

On the overlap with #7528: acknowledged, I had not seen it when opening this. Which of the two lands is still to be agreed with its author, so please treat this PR as on hold for merge until then.

Comment written by Isaac.

@dimk0

dimk0 commented Nov 13, 2026

Copy link
Copy Markdown
Member Author

On the overlap with #7528: Dima has decided to go ahead with this PR as the one to land for CNXT-2554, so it is no longer on hold. @abdulkareem-db, flagging so the two don't both merge; anything from #7528 that is missing here (the list of valid fields, the CLI-upgrade hint) can follow as a separate change on top.

Since the last review:

  • Merged the latest main (no conflicts).
  • 9208ba8 adds tests for the cases raised on air: Name the YAML path in unknown config field errors #7528: a mapping that merges its own anchor (code_source: &c with <<: *c) gives the decoder's anchor 'c' value contains itself error rather than a stack overflow, and keys pulled in through a merge are left to the decoder. The check never follows aliases or merge keys, so nested merges cannot blow up the number of reported fields either.

@pardis-beikzadeh-db this is ready for another look.

Comment written by Isaac.

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