Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .nextchanges/air/unknown-config-field.md
Original file line number Diff line number Diff line change
@@ -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))
10 changes: 10 additions & 0 deletions acceptance/air/run/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions acceptance/air/run/script
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
7 changes: 7 additions & 0 deletions acceptance/air/run/unknown-field.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
experiment_name: my-run
command: python train.py
compute:
accelerator_type: GPU_1xH100
num_accelerators: 1
enviroment:
dependencies: [numpy]
19 changes: 13 additions & 6 deletions cmd/air/runconfig.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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
Expand Down
71 changes: 71 additions & 0 deletions cmd/air/runconfig_load.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import (
"io"
"os"
"regexp"
"slices"
"strconv"
"strings"
"sync"
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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.<field>` 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:
Comment thread
dimk0 marked this conversation as resolved.
Resolved
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
Comment thread
dimk0 marked this conversation as resolved.
Resolved
}
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 {
Expand Down
10 changes: 1 addition & 9 deletions cmd/air/runconfig_override.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ import (
"context"
"errors"
"fmt"
"slices"
"strings"

"github.com/databricks/cli/libs/cmdio"
Expand Down Expand Up @@ -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, ", "))
}
Expand Down
90 changes: 86 additions & 4 deletions cmd/air/runconfig_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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) {
Comment thread
dimk0 marked this conversation as resolved.
Resolved
_, 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)
})
}

Expand Down
Loading