diff --git a/.nextchanges/air/unknown-config-field.md b/.nextchanges/air/unknown-config-field.md new file mode 100644 index 00000000000..d6f449f471a --- /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. ([#7574](https://github.com/databricks/cli/pull/7574)) diff --git a/acceptance/air/run/output.txt b/acceptance/air/run/output.txt index 8bb2f5c4cce..e9ea843f2cf 100644 --- a/acceptance/air/run/output.txt +++ b/acceptance/air/run/output.txt @@ -85,6 +85,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 4b0163bdec2..467133f342a 100644 --- a/acceptance/air/run/script +++ b/acceptance/air/run/script @@ -39,6 +39,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..131408a0007 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,73 @@ 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 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 { + // 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 { + if element.Kind == yaml.MappingNode { + unknown = append(unknown, unknownConfigFields(element, field, helpPath, keys)...) + } + } + case yaml.MappingNode: + 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 helpPath == field.path && !child.hidden { + childHelpPath = child.path + } + unknown = append(unknown, unknownConfigFields(value, child, childHelpPath, keyPath)...) + } + default: + // Scalars hold no keys, and aliases are left to the decoder. + } + 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..139504e1618 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,94 @@ 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("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("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) }) }