From bec94d970624b60b54e6ff72723ab509a70467bb Mon Sep 17 00:00:00 2001 From: "dima.kotlyarov" <4886215+dimk0@users.noreply.github.com> Date: Thu, 12 Nov 2026 20:22:58 +0000 Subject: [PATCH 1/4] [CNXT-2554] air: explain unknown workload YAML keys 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 --- .nextchanges/air/unknown-config-field.md | 1 + acceptance/air/run/output.txt | 10 ++++ acceptance/air/run/script | 3 ++ acceptance/air/run/unknown-field.yaml | 7 +++ cmd/air/runconfig.go | 19 ++++--- cmd/air/runconfig_load.go | 69 ++++++++++++++++++++++++ cmd/air/runconfig_override.go | 10 +--- cmd/air/runconfig_test.go | 56 +++++++++++++++++-- 8 files changed, 156 insertions(+), 19 deletions(-) create mode 100644 .nextchanges/air/unknown-config-field.md create mode 100644 acceptance/air/run/unknown-field.yaml diff --git a/.nextchanges/air/unknown-config-field.md b/.nextchanges/air/unknown-config-field.md new file mode 100644 index 00000000000..99e407a69e3 --- /dev/null +++ b/.nextchanges/air/unknown-config-field.md @@ -0,0 +1 @@ +* `databricks air run` now reports an unknown workload YAML key by its field path, suggests the closest valid field, and points to `-h config` instead of naming an internal Go type. diff --git a/acceptance/air/run/output.txt b/acceptance/air/run/output.txt index 8e71b6bcfd8..9df75befdab 100644 --- a/acceptance/air/run/output.txt +++ b/acceptance/air/run/output.txt @@ -74,6 +74,16 @@ Tip: use the --debug flag to see more details and a trace of this error: Exit code: 1 +=== 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 + +Tip: use the --debug flag to see more details and a trace of this error: + databricks --debug air run … + +Exit code: 1 + === missing --file >>> [CLI] air run --dry-run diff --git a/acceptance/air/run/script b/acceptance/air/run/script index 835d78f6928..a8be73d3263 100644 --- a/acceptance/air/run/script +++ b/acceptance/air/run/script @@ -25,6 +25,9 @@ errcode trace $CLI air run -f git-remote.yaml --dry-run title "invalid config is rejected" errcode trace $CLI air run -f invalid.yaml --dry-run +title "unknown field suggests the near match" +errcode trace $CLI air run -f unknown-field.yaml --dry-run + title "missing --file" errcode trace $CLI air run --dry-run diff --git a/acceptance/air/run/unknown-field.yaml b/acceptance/air/run/unknown-field.yaml new file mode 100644 index 00000000000..dfcfa76304b --- /dev/null +++ b/acceptance/air/run/unknown-field.yaml @@ -0,0 +1,7 @@ +experiment_name: my-run +command: python train.py +compute: + accelerator_type: GPU_1xH100 + num_accelerators: 1 +enviroment: + dependencies: [numpy] diff --git a/cmd/air/runconfig.go b/cmd/air/runconfig.go index 78554b02183..637ded38e4e 100644 --- a/cmd/air/runconfig.go +++ b/cmd/air/runconfig.go @@ -730,6 +730,18 @@ func cutLast(s, sep string) (before, after string, found bool) { // unknownConfigFieldError reports an unresolvable segment, naming the valid // siblings and, when one is close enough, a suggestion. func unknownConfigFieldError(parent configField, part string, matched []string) error { + names := visibleConfigChildNames(parent) + + msg := fmt.Sprintf("unknown config field %q", configHelpRoot+"."+strings.Join(matched, ".")) + if suggestion, ok := closestConfigField(part, names); ok { + msg += fmt.Sprintf("; did you mean %q?", suggestion) + } + return fmt.Errorf("%s\n\nfields under %q are: %s", msg, parent.path, strings.Join(names, ", ")) +} + +// visibleConfigChildNames returns the sorted YAML names of a field's documented +// children. +func visibleConfigChildNames(parent configField) []string { names := make([]string, 0, len(parent.children)) for _, c := range parent.children { if c.hidden { @@ -738,12 +750,7 @@ func unknownConfigFieldError(parent configField, part string, matched []string) names = append(names, configLeafName(c.path)) } slices.Sort(names) - - msg := fmt.Sprintf("unknown config field %q", configHelpRoot+"."+strings.Join(matched, ".")) - if suggestion, ok := closestConfigField(part, names); ok { - msg += fmt.Sprintf("; did you mean %q?", suggestion) - } - return fmt.Errorf("%s\n\nfields under %q are: %s", msg, parent.path, strings.Join(names, ", ")) + return names } // closestConfigField returns the nearest candidate by edit distance, if one is diff --git a/cmd/air/runconfig_load.go b/cmd/air/runconfig_load.go index 2e05e1b50e6..bbe3d37d79d 100644 --- a/cmd/air/runconfig_load.go +++ b/cmd/air/runconfig_load.go @@ -8,6 +8,7 @@ import ( "io" "os" "regexp" + "slices" "strconv" "strings" "sync" @@ -98,6 +99,9 @@ func readRunConfigDocument(path string) (*yaml.Node, []byte, error) { } func finishRunConfigLoad(path string, document *yaml.Node, validationYAML []byte) (*runConfig, error) { + if err := checkUnknownConfigFields(path, document.Content[0]); err != nil { + return nil, err + } // Validate before stripping comments so YAML errors retain source line numbers. cfg, err := decodeRunConfigReader(bytes.NewReader(validationYAML), path) if err != nil { @@ -125,6 +129,71 @@ func finishRunConfigLoad(path string, document *yaml.Node, validationYAML []byte return cfg, nil } +// checkUnknownConfigFields rejects keys absent from the run config schema. The +// strict decode that follows rejects them too, but its error names the Go struct +// rather than the field's path and offers no suggestion. +func checkUnknownConfigFields(path string, root *yaml.Node) error { + schema := configSchema() + unknown := unknownConfigFields(root, schema, schema.path, nil) + switch len(unknown) { + case 0: + return nil + case 1: + return fmt.Errorf("invalid config %s: %s", path, unknown[0]) + default: + return fmt.Errorf("invalid config %s:\n %s", path, strings.Join(unknown, "\n ")) + } +} + +// unknownConfigFields describes each key under node that field's schema does not +// define. helpPath is the nearest documented ancestor, since hidden fields have +// no `-h config.` page. Sequences add no path segment, matching how the +// schema addresses list elements. +func unknownConfigFields(node *yaml.Node, field configField, helpPath string, keys []string) []string { + if node.Kind == yaml.AliasNode { + node = node.Alias + } + var unknown []string + switch node.Kind { + case yaml.SequenceNode: + for _, element := range node.Content { + unknown = append(unknown, unknownConfigFields(element, field, helpPath, keys)...) + } + case yaml.MappingNode: + // Only objects have schema-defined keys; free-form maps and leaves do not. + if len(field.children) == 0 { + return nil + } + for i := 0; i+1 < len(node.Content); i += 2 { + key, value := node.Content[i], node.Content[i+1] + // A merge key pulls in another mapping's keys; the strict decode checks those. + if key.Tag == "!!merge" { + continue + } + keyPath := append(slices.Clone(keys), key.Value) + child, ok := findConfigChild(field.children, key.Value) + if !ok { + msg := fmt.Sprintf("line %d: unknown field %q", key.Line, strings.Join(keyPath, ".")) + if suggestion, ok := closestConfigField(key.Value, visibleConfigChildNames(field)); ok { + msg += fmt.Sprintf("; did you mean %q? Run", suggestion) + } else { + msg += "; run" + } + unknown = append(unknown, fmt.Sprintf("%s \"databricks air run -h %s\" for the list of fields", msg, helpPath)) + continue + } + childHelpPath := helpPath + if !child.hidden { + childHelpPath = child.path + } + unknown = append(unknown, unknownConfigFields(value, child, childHelpPath, keyPath)...) + } + default: + // Scalars hold no keys. + } + return unknown +} + func codeSourceFieldPresent(document *yaml.Node, field string) bool { codeSource, _ := mappingValue(document.Content[0], "code_source") if codeSource == nil || codeSource.Kind != yaml.MappingNode { diff --git a/cmd/air/runconfig_override.go b/cmd/air/runconfig_override.go index 3fbccd076cb..306308edfd4 100644 --- a/cmd/air/runconfig_override.go +++ b/cmd/air/runconfig_override.go @@ -4,7 +4,6 @@ import ( "context" "errors" "fmt" - "slices" "strings" "github.com/databricks/cli/libs/cmdio" @@ -65,14 +64,7 @@ func checkOverridePath(parts []string, node configField, fullPath string) error name := parts[0] child, ok := findConfigChild(node.children, name) if !ok { - names := make([]string, 0, len(node.children)) - for _, c := range node.children { - if c.hidden { - continue - } - names = append(names, configLeafName(c.path)) - } - slices.Sort(names) + names := visibleConfigChildNames(node) return fmt.Errorf("invalid --override %q: %q is not a known field; available fields are: %s", fullPath, name, strings.Join(names, ", ")) } diff --git a/cmd/air/runconfig_test.go b/cmd/air/runconfig_test.go index 74b4c187628..56d652f11ae 100644 --- a/cmd/air/runconfig_test.go +++ b/cmd/air/runconfig_test.go @@ -137,8 +137,8 @@ func TestLoadRunConfig_CodeSourceErrors(t *testing.T) { {"flattened error path", "code_source:\n root_path: \"\"\n", "code_source.root_path cannot be empty"}, {"nested error path", "code_source:\n snapshot:\n root_path: \"\"\n", "code_source.snapshot.root_path cannot be empty"}, {"null snapshot", "code_source:\n snapshot: null\n", "code_source.snapshot.root_path cannot be empty"}, - {"unknown flattened field", "code_source:\n root_path: src\n bogus: true\n", "field bogus not found"}, - {"unknown nested field", "code_source:\n snapshot:\n root_path: src\n bogus: true\n", "field bogus not found"}, + {"unknown flattened field", "code_source:\n root_path: src\n bogus: true\n", `unknown field "code_source.bogus"`}, + {"unknown nested field", "code_source:\n snapshot:\n root_path: src\n bogus: true\n", `unknown field "code_source.snapshot.bogus"`}, } for _, tt := range tests { @@ -339,12 +339,60 @@ unknown_field: true t.Run("without overrides", func(t *testing.T) { _, err := loadRunConfig(path) - require.ErrorContains(t, err, "line 8: field unknown_field") + require.ErrorContains(t, err, `line 8: unknown field "unknown_field"`) }) t.Run("with overrides", func(t *testing.T) { _, err := loadRunConfigWithOverrides(t.Context(), path, []string{"compute.num_accelerators=2"}) - require.ErrorContains(t, err, "line 8: field unknown_field") + require.ErrorContains(t, err, `line 8: unknown field "unknown_field"`) + }) +} + +func TestLoadRunConfig_UnknownFieldErrors(t *testing.T) { + tests := []struct { + name string + yaml string + want string + }{ + { + "top-level typo suggests the field", + minimalConfig + "environmnt:\n dependencies: [numpy]\n", + `line 7: unknown field "environmnt"; did you mean "environment"? Run "databricks air run -h config" for the list of fields`, + }, + { + "nested typo names the path and its parent's help", + "experiment_name: r\ncommand: x\ncompute:\n acclerator_type: GPU_1xH100\n num_accelerators: 1\n", + `line 4: unknown field "compute.acclerator_type"; did you mean "accelerator_type"? Run "databricks air run -h config.compute" for the list of fields`, + }, + { + "no close match omits the suggestion", + minimalConfig + "zzz: true\n", + `line 7: unknown field "zzz"; run "databricks air run -h config" for the list of fields`, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + path := writeConfig(t, tt.yaml) + _, err := loadRunConfig(path) + require.EqualError(t, err, "invalid config "+path+": "+tt.want) + }) + } + + t.Run("several unknown fields are all reported", func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+"environmnt: {}\nzzz: true\n")) + require.ErrorContains(t, err, `line 7: unknown field "environmnt"`) + require.ErrorContains(t, err, `line 8: unknown field "zzz"`) + assert.NotContains(t, err.Error(), "aircmd") + }) + + t.Run("list elements and hidden parents resolve", func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+"code_source:\n snapshot:\n root_path: src\n remote_volum: /Volumes/a/b/c\n")) + require.ErrorContains(t, err, `unknown field "code_source.snapshot.remote_volum"; did you mean "remote_volume"? Run "databricks air run -h config.code_source" for the list of fields`) + }) + + t.Run("free-form maps accept any key", func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+"parameters:\n environmnt: 1\n nested:\n zzz: 2\n")) + require.NoError(t, err) }) } From 03f29717915defc60414f50af3e7a872fd293192 Mon Sep 17 00:00:00 2001 From: "dima.kotlyarov" <4886215+dimk0@users.noreply.github.com> Date: Thu, 12 Nov 2026 20:23:26 +0000 Subject: [PATCH 2/4] Link the changelog fragment to the PR Co-authored-by: Isaac --- .nextchanges/air/unknown-config-field.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.nextchanges/air/unknown-config-field.md b/.nextchanges/air/unknown-config-field.md index 99e407a69e3..d6f449f471a 100644 --- a/.nextchanges/air/unknown-config-field.md +++ b/.nextchanges/air/unknown-config-field.md @@ -1 +1 @@ -* `databricks air run` now reports an unknown workload YAML key by its field path, suggests the closest valid field, and points to `-h config` instead of naming an internal Go type. +* `databricks air run` now reports an unknown workload YAML key by its field path, suggests the closest valid field, and points to `-h config` instead of naming an internal Go type. ([#7574](https://github.com/databricks/cli/pull/7574)) From 92fbf894aed7bd3f697a1c1d7695ee201689914e Mon Sep 17 00:00:00 2001 From: "dima.kotlyarov" <4886215+dimk0@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:39:44 +0000 Subject: [PATCH 3/4] Leave aliases and nested lists to the decoder in the unknown-field check 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 --- cmd/air/runconfig_load.go | 26 ++++++++++++++------------ cmd/air/runconfig_test.go | 24 ++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 12 deletions(-) diff --git a/cmd/air/runconfig_load.go b/cmd/air/runconfig_load.go index bbe3d37d79d..131408a0007 100644 --- a/cmd/air/runconfig_load.go +++ b/cmd/air/runconfig_load.go @@ -146,24 +146,26 @@ func checkUnknownConfigFields(path string, root *yaml.Node) error { } // unknownConfigFields describes each key under node that field's schema does not -// define. helpPath is the nearest documented ancestor, since hidden fields have -// no `-h config.` page. Sequences add no path segment, matching how the -// schema addresses list elements. +// define. helpPath is the nearest documented ancestor, since a hidden field and +// everything below it have no `-h config.` page. Sequences add no path +// segment, matching how the schema addresses list elements. +// +// Aliases are never followed: one may point at its own ancestor, and the strict +// decode checks whatever they expand to. func unknownConfigFields(node *yaml.Node, field configField, helpPath string, keys []string) []string { - if node.Kind == yaml.AliasNode { - node = node.Alias + // Only objects have schema-defined keys; free-form maps and leaves do not. + if len(field.children) == 0 { + return nil } var unknown []string switch node.Kind { case yaml.SequenceNode: for _, element := range node.Content { - unknown = append(unknown, unknownConfigFields(element, field, helpPath, keys)...) + if element.Kind == yaml.MappingNode { + unknown = append(unknown, unknownConfigFields(element, field, helpPath, keys)...) + } } case yaml.MappingNode: - // Only objects have schema-defined keys; free-form maps and leaves do not. - if len(field.children) == 0 { - return nil - } for i := 0; i+1 < len(node.Content); i += 2 { key, value := node.Content[i], node.Content[i+1] // A merge key pulls in another mapping's keys; the strict decode checks those. @@ -183,13 +185,13 @@ func unknownConfigFields(node *yaml.Node, field configField, helpPath string, ke continue } childHelpPath := helpPath - if !child.hidden { + if helpPath == field.path && !child.hidden { childHelpPath = child.path } unknown = append(unknown, unknownConfigFields(value, child, childHelpPath, keyPath)...) } default: - // Scalars hold no keys. + // Scalars hold no keys, and aliases are left to the decoder. } return unknown } diff --git a/cmd/air/runconfig_test.go b/cmd/air/runconfig_test.go index 56d652f11ae..91dfb6b9cae 100644 --- a/cmd/air/runconfig_test.go +++ b/cmd/air/runconfig_test.go @@ -390,6 +390,30 @@ func TestLoadRunConfig_UnknownFieldErrors(t *testing.T) { require.ErrorContains(t, err, `unknown field "code_source.snapshot.remote_volum"; did you mean "remote_volume"? Run "databricks air run -h config.code_source" for the list of fields`) }) + t.Run("list elements resolve against the element schema", func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+"containers:\n - name: a\n comand: x\n")) + require.ErrorContains(t, err, `line 9: unknown field "containers.comand"; did you mean "command"? Run "databricks air run -h config.containers" for the list of fields`) + }) + + t.Run("help stays at the nearest documented ancestor below a hidden field", func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+"code_source:\n snapshot:\n root_path: src\n git:\n brnch: main\n")) + require.ErrorContains(t, err, `unknown field "code_source.snapshot.git.brnch"; did you mean "branch"? Run "databricks air run -h config.code_source" for the list of fields`) + }) + + // The schema check must leave aliases to the decoder: following one that + // points at its own ancestor never terminates. + for name, extra := range map[string]string{ + "string list": "code_source:\n root_path: src\n include_paths: &p [a, *p]\n", + "object list": "containers: &c [*c]\n", + "free-form": "parameters: &p [*p]\n", + "nested lists": "containers: [[{comand: x}]]\n", + } { + t.Run("decoder reports "+name, func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+extra)) + require.ErrorContains(t, err, "cannot unmarshal") + }) + } + t.Run("free-form maps accept any key", func(t *testing.T) { _, err := loadRunConfig(writeConfig(t, minimalConfig+"parameters:\n environmnt: 1\n nested:\n zzz: 2\n")) require.NoError(t, err) From 9208ba8b8cf80c19324574a5b7a4af2072d5f9d9 Mon Sep 17 00:00:00 2001 From: "dima.kotlyarov" <4886215+dimk0@users.noreply.github.com> Date: Fri, 13 Nov 2026 07:04:42 +0000 Subject: [PATCH 4/4] Test that self-merging mappings are left to the decoder Co-authored-by: Isaac --- cmd/air/runconfig_test.go | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cmd/air/runconfig_test.go b/cmd/air/runconfig_test.go index 91dfb6b9cae..139504e1618 100644 --- a/cmd/air/runconfig_test.go +++ b/cmd/air/runconfig_test.go @@ -414,6 +414,16 @@ func TestLoadRunConfig_UnknownFieldErrors(t *testing.T) { }) } + t.Run("decoder reports a mapping that merges itself", func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+"code_source: &c\n root_path: src\n <<: *c\n")) + require.ErrorContains(t, err, "anchor 'c' value contains itself") + }) + + t.Run("unknown keys pulled in by a merge are left to the decoder", func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+"x-base: &b\n root_path: src\ncode_source:\n <<: *b\n")) + require.ErrorContains(t, err, `line 7: unknown field "x-base"; run "databricks air run -h config" for the list of fields`) + }) + t.Run("free-form maps accept any key", func(t *testing.T) { _, err := loadRunConfig(writeConfig(t, minimalConfig+"parameters:\n environmnt: 1\n nested:\n zzz: 2\n")) require.NoError(t, err)