From 410fe30b1033c86fcd523fdd0e7fd450674f0113 Mon Sep 17 00:00:00 2001 From: dimk0 <4886215+dimk0@users.noreply.github.com> Date: Thu, 12 Nov 2026 20:45:38 +0000 Subject: [PATCH 1/3] air: explain root_path and default retries in convert-to-dabs convert-to-dabs rejects a code_source root_path that resolves to the bundle root without saying how to proceed, and writes the air run default max_retries into the bundle without mentioning it. Point at the subdirectory and --output-dir fixes in the error, and print a note when the generated job carries the default retry settings. Co-authored-by: Isaac --- .../air/convert-to-dabs-root-path-retries.md | 1 + acceptance/air/convert-to-dabs/output.txt | 12 ++++++++++++ cmd/air/convert_to_dabs.go | 17 ++++++++++++++++- cmd/air/convert_to_dabs_test.go | 12 ++++++++++++ 4 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 .nextchanges/air/convert-to-dabs-root-path-retries.md diff --git a/.nextchanges/air/convert-to-dabs-root-path-retries.md b/.nextchanges/air/convert-to-dabs-root-path-retries.md new file mode 100644 index 00000000000..219cc37d1eb --- /dev/null +++ b/.nextchanges/air/convert-to-dabs-root-path-retries.md @@ -0,0 +1 @@ +* `air convert-to-dabs` now explains the `--output-dir` workaround when `code_source.root_path` resolves to the bundle root, and notes when the generated job carries the default `max_retries`. diff --git a/acceptance/air/convert-to-dabs/output.txt b/acceptance/air/convert-to-dabs/output.txt index 7a0beec224b..707b03a2eec 100644 --- a/acceptance/air/convert-to-dabs/output.txt +++ b/acceptance/air/convert-to-dabs/output.txt @@ -20,6 +20,9 @@ persistent job that is not garbage-collected. When you are done, remove the job and its uploaded files with: [CLI] bundle destroy +Note: the YAML does not set max_retries, so the job uses the `air run` default +(max_retries: 3, retry_on_timeout: true). Edit databricks.yml to change it. + === emitted databricks.yml (code_source packaged as a tgz artifact; no code is copied) >>> cat databricks.yml @@ -111,6 +114,9 @@ persistent job that is not garbage-collected. When you are done, remove the job and its uploaded files with: [CLI] bundle destroy +Note: the YAML does not set max_retries, so the job uses the `air run` default +(max_retries: 3, retry_on_timeout: true). Edit databricks.yml to change it. + === convert a B300 run using the current SDK >>> [CLI] air convert-to-dabs b300.yaml --output-dir generated-b300 @@ -133,6 +139,9 @@ persistent job that is not garbage-collected. When you are done, remove the job and its uploaded files with: [CLI] bundle destroy +Note: the YAML does not set max_retries, so the job uses the `air run` default +(max_retries: 3, retry_on_timeout: true). Edit databricks.yml to change it. + === the B300 bundle preserves its accelerator and AI Runtime version >>> cat generated-b300/databricks.yml @@ -198,6 +207,9 @@ persistent job that is not garbage-collected. When you are done, remove the job and its uploaded files with: [CLI] bundle destroy +Note: the YAML does not set max_retries, so the job uses the `air run` default +(max_retries: 3, retry_on_timeout: true). Edit databricks.yml to change it. + >>> grep -E environment_version|base_environment databricks.yml base_environment: workspace-base-environments/databricks_ai_v5 diff --git a/cmd/air/convert_to_dabs.go b/cmd/air/convert_to_dabs.go index dcb90cfea00..90132c46b0f 100644 --- a/cmd/air/convert_to_dabs.go +++ b/cmd/air/convert_to_dabs.go @@ -103,6 +103,10 @@ does not contact the workspace.`, } printConvertNextSteps(ctx, dir, written, bundleResourceKey(cfg.ExperimentName)) + if note := retryDefaultsNote(cfg); note != "" { + cmdio.LogString(ctx, "") + cmdio.LogString(ctx, note) + } return nil } @@ -206,7 +210,7 @@ func codeArtifactFor(cfg *runConfig, codeDirPath string) (*codeArtifact, error) // generated_artifacts/, the output tarball) into it. Reject rather than emit that; // the user should point root_path at a subdirectory. if codeDirRel == "." { - return nil, fmt.Errorf("code_source root_path %q resolves to the bundle root; convert-to-dabs cannot package code there (no code directory to nest under %s/). Point root_path at a subdirectory", snap.RootPath, runtimeCodeSourceRoot) + return nil, fmt.Errorf("code_source root_path %q resolves to the bundle root; convert-to-dabs cannot package code there (no code directory to nest under %s/). Move the code into a subdirectory (for example ./src) and point root_path at it, or pass --output-dir with a parent directory that contains the code directory", snap.RootPath, runtimeCodeSourceRoot) } dirName := path.Base(codeDirRel) art := &codeArtifact{ @@ -647,6 +651,17 @@ func printConvertNextSteps(ctx context.Context, dir string, written []string, jo cmdio.LogString(ctx, " "+self+" bundle destroy") } +// retryDefaultsNote reports the retry settings the bundle carries that the YAML does +// not spell out. `air run` applies them implicitly on every submit, but in a bundle +// they are written down, so without the note they look invented by the conversion. +// Returns "" when the YAML sets max_retries. +func retryDefaultsNote(cfg *runConfig) string { + if cfg.MaxRetries != nil { + return "" + } + return fmt.Sprintf("Note: the YAML does not set max_retries, so the job uses the `air run` default\n(max_retries: %d, retry_on_timeout: true). Edit databricks.yml to change it.", defaultMaxRetries) +} + // cliInvocation is how the user should spell this binary in a follow-up command. // A path-qualified argv[0] (./dbcli, ../dbcli) is kept as typed so copy-paste works // from the same cwd; a bare name resolved via PATH is reported as "databricks". diff --git a/cmd/air/convert_to_dabs_test.go b/cmd/air/convert_to_dabs_test.go index ba2c4ce6f71..d647cf9f6fd 100644 --- a/cmd/air/convert_to_dabs_test.go +++ b/cmd/air/convert_to_dabs_test.go @@ -648,10 +648,22 @@ func TestConvertToDabsDotRootPathRejected(t *testing.T) { _, _, err = convertToDabs(t.Context(), loaded, path, dir) require.ErrorContains(t, err, "resolves to the bundle root") + require.ErrorContains(t, err, "--output-dir") }) } } +func TestRetryDefaultsNote(t *testing.T) { + // Unset: the bundle carries the `air run` default, which the YAML never mentions. + note := retryDefaultsNote(&runConfig{}) + assert.Contains(t, note, "max_retries: 3") + assert.Contains(t, note, "retry_on_timeout: true") + + // Set (including 0): the bundle value is the user's own, so there is nothing to explain. + assert.Empty(t, retryDefaultsNote(&runConfig{MaxRetries: new(0)})) + assert.Empty(t, retryDefaultsNote(&runConfig{MaxRetries: new(2)})) +} + func TestConvertToDabsRejectsUnsupported(t *testing.T) { t.Run("usage_policy_name", func(t *testing.T) { cfg := minimalConfig + "usage_policy_name: my-policy\n" From 9344890864cce5bb74e8e17ab7820e7a5e49a5bd Mon Sep 17 00:00:00 2001 From: dimk0 <4886215+dimk0@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:10:06 +0000 Subject: [PATCH 2/3] Add PR link to changelog fragment Co-authored-by: Isaac --- .nextchanges/air/convert-to-dabs-root-path-retries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.nextchanges/air/convert-to-dabs-root-path-retries.md b/.nextchanges/air/convert-to-dabs-root-path-retries.md index 219cc37d1eb..2e57c98fa72 100644 --- a/.nextchanges/air/convert-to-dabs-root-path-retries.md +++ b/.nextchanges/air/convert-to-dabs-root-path-retries.md @@ -1 +1 @@ -* `air convert-to-dabs` now explains the `--output-dir` workaround when `code_source.root_path` resolves to the bundle root, and notes when the generated job carries the default `max_retries`. +* `air convert-to-dabs` now explains the `--output-dir` workaround when `code_source.root_path` resolves to the bundle root, and notes when the generated job carries the default `max_retries`. ([#7579](https://github.com/databricks/cli/pull/7579)) From b58c19e17fe792124b62b7491916324ad7f8a13a Mon Sep 17 00:00:00 2001 From: dimk0 <4886215+dimk0@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:42:30 +0000 Subject: [PATCH 3/3] air: limit the --output-dir hint to working-tree snapshots A git snapshot is archived from the bundle root, so rooting the bundle at a parent directory fails at deploy. Offer --output-dir only when there is no git ref, derive retry_on_timeout in the retry note, fix comments the new error made stale, and cover the plain-snapshot rejection, the parent output-dir conversion, and note suppression at the command level. Co-authored-by: Isaac --- cmd/air/convert_to_dabs.go | 25 ++++++----- cmd/air/convert_to_dabs_test.go | 73 +++++++++++++++++++++++++++++---- 2 files changed, 79 insertions(+), 19 deletions(-) diff --git a/cmd/air/convert_to_dabs.go b/cmd/air/convert_to_dabs.go index 90132c46b0f..363bc07e4d7 100644 --- a/cmd/air/convert_to_dabs.go +++ b/cmd/air/convert_to_dabs.go @@ -207,10 +207,16 @@ func codeArtifactFor(cfg *runConfig, codeDirPath string) (*codeArtifact, error) // A code dir that resolves to the bundle root has no basename to nest under: the // archive would sit directly at /databricks/code_source (no ), and an include // rooted at "." would also sweep the bundle's own generated files (databricks.yml, - // generated_artifacts/, the output tarball) into it. Reject rather than emit that; - // the user should point root_path at a subdirectory. + // generated_artifacts/, the output tarball) into it. Reject rather than emit that. if codeDirRel == "." { - return nil, fmt.Errorf("code_source root_path %q resolves to the bundle root; convert-to-dabs cannot package code there (no code directory to nest under %s/). Move the code into a subdirectory (for example ./src) and point root_path at it, or pass --output-dir with a parent directory that contains the code directory", snap.RootPath, runtimeCodeSourceRoot) + remedy := "move the code into a subdirectory (for example ./src) and point root_path at it" + // A bundle rooted at the parent only works for a working-tree snapshot: a git + // snapshot is archived from the bundle root, which would then sit outside the + // repository (or inside an unrelated one). + if snap.Git == nil { + remedy += ", or pass --output-dir with a dedicated parent directory that contains the code directory" + } + return nil, fmt.Errorf("code_source root_path %q resolves to the bundle root, so there is no code directory to nest under %s/; %s", snap.RootPath, runtimeCodeSourceRoot, remedy) } dirName := path.Base(codeDirRel) art := &codeArtifact{ @@ -562,8 +568,8 @@ func writeBundle(ctx context.Context, cfg *runConfig, configPath, dir string, fo // Refuse to clobber an existing file, with one consistent message. A user // re-running convert into the same dir gets a clear error rather than a silent // overwrite of edits they may have made. The hint names --force rather than - // --output-dir: the code_source must live inside the bundle dir, so redirecting - // the output usually isn't a usable escape hatch for an in-place conversion. + // --output-dir: a re-run is replacing a bundle that already sits where the + // code_source needs it, so writing a second copy elsewhere isn't what the user wants. artifactDir := filepath.Join(dir, generatedArtifactsDir) if err := os.MkdirAll(artifactDir, 0o700); err != nil { return nil, err @@ -651,15 +657,14 @@ func printConvertNextSteps(ctx context.Context, dir string, written []string, jo cmdio.LogString(ctx, " "+self+" bundle destroy") } -// retryDefaultsNote reports the retry settings the bundle carries that the YAML does -// not spell out. `air run` applies them implicitly on every submit, but in a bundle -// they are written down, so without the note they look invented by the conversion. -// Returns "" when the YAML sets max_retries. +// retryDefaultsNote explains retry settings the bundle carries but the YAML omits: +// `air run` applies them implicitly, so written down they look invented by the +// conversion. Returns "" when the YAML sets max_retries. func retryDefaultsNote(cfg *runConfig) string { if cfg.MaxRetries != nil { return "" } - return fmt.Sprintf("Note: the YAML does not set max_retries, so the job uses the `air run` default\n(max_retries: %d, retry_on_timeout: true). Edit databricks.yml to change it.", defaultMaxRetries) + return fmt.Sprintf("Note: the YAML does not set max_retries, so the job uses the `air run` default\n(max_retries: %d, retry_on_timeout: %t). Edit databricks.yml to change it.", defaultMaxRetries, defaultMaxRetries > 0) } // cliInvocation is how the user should spell this binary in a follow-up command. diff --git a/cmd/air/convert_to_dabs_test.go b/cmd/air/convert_to_dabs_test.go index d647cf9f6fd..1ac0a4f8c3c 100644 --- a/cmd/air/convert_to_dabs_test.go +++ b/cmd/air/convert_to_dabs_test.go @@ -6,6 +6,7 @@ import ( "strings" "testing" + "github.com/databricks/cli/libs/cmdio" "github.com/databricks/cli/libs/dyn" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -628,13 +629,17 @@ func TestConvertToDabsIncludePathsDirectories(t *testing.T) { // root_path "." (the code source is the whole bundle directory) has no basename to // nest the archive under, and an include rooted at "." would sweep the bundle's own -// generated files into the tarball — so a git/include snapshot there is rejected with -// a message pointing at a subdirectory. (A plain snapshot with root_path "." is not an -// artifact case and is unaffected.) +// generated files into the tarball, so every snapshot there is rejected. Only a +// working-tree snapshot is offered --output-dir: a git snapshot is archived from the +// bundle root, which a parent directory would move outside the repository. func TestConvertToDabsDotRootPathRejected(t *testing.T) { - for _, tc := range []struct{ name, snap string }{ - {"git", "code_source:\n type: snapshot\n snapshot:\n root_path: .\n git:\n commit: abc123\n"}, - {"include", "code_source:\n type: snapshot\n snapshot:\n root_path: .\n include_paths:\n - foo\n"}, + for _, tc := range []struct { + name, snap string + wantOutputDirHint bool + }{ + {"plain", "code_source:\n type: snapshot\n snapshot:\n root_path: .\n", true}, + {"include", "code_source:\n type: snapshot\n snapshot:\n root_path: .\n include_paths:\n - foo\n", true}, + {"git", "code_source:\n type: snapshot\n snapshot:\n root_path: .\n git:\n commit: abc123\n", false}, } { t.Run(tc.name, func(t *testing.T) { dir := t.TempDir() @@ -648,22 +653,72 @@ func TestConvertToDabsDotRootPathRejected(t *testing.T) { _, _, err = convertToDabs(t.Context(), loaded, path, dir) require.ErrorContains(t, err, "resolves to the bundle root") - require.ErrorContains(t, err, "--output-dir") + require.ErrorContains(t, err, "subdirectory") + if tc.wantOutputDirHint { + require.ErrorContains(t, err, "--output-dir") + } else { + require.NotContains(t, err.Error(), "--output-dir") + } }) } } +// The --output-dir remedy the rejection suggests: with the bundle rooted at the +// parent, the code dir has a basename to nest under and converts. +func TestConvertToDabsDotRootPathWithParentOutputDir(t *testing.T) { + parent := t.TempDir() + dir := filepath.Join(parent, "proj") + require.NoError(t, os.MkdirAll(dir, 0o700)) + cfg := "experiment_name: dot\ncommand: python train.py\n" + + "compute: {accelerator_type: GPU_1xA10, num_accelerators: 1}\n" + + "code_source:\n type: snapshot\n snapshot:\n root_path: .\n" + path := filepath.Join(dir, "run.yaml") + require.NoError(t, os.WriteFile(path, []byte(cfg), 0o600)) + loaded, err := loadRunConfig(path) + require.NoError(t, err) + + root, _, err := convertToDabs(t.Context(), loaded, path, parent) + require.NoError(t, err) + + a := "artifacts." + codeSourceArtifactKey + assert.Equal(t, ".", get(t, root, a+".path").MustString()) + inc := get(t, root, a+".include").MustSequence() + require.Len(t, inc, 1) + assert.Equal(t, "proj", inc[0].MustString()) +} + func TestRetryDefaultsNote(t *testing.T) { - // Unset: the bundle carries the `air run` default, which the YAML never mentions. note := retryDefaultsNote(&runConfig{}) assert.Contains(t, note, "max_retries: 3") assert.Contains(t, note, "retry_on_timeout: true") - // Set (including 0): the bundle value is the user's own, so there is nothing to explain. + // An explicit value, including 0, is the user's own: nothing to explain. assert.Empty(t, retryDefaultsNote(&runConfig{MaxRetries: new(0)})) assert.Empty(t, retryDefaultsNote(&runConfig{MaxRetries: new(2)})) } +func TestConvertToDabsCommandPrintsRetryNoteOnlyWhenUnset(t *testing.T) { + for _, tc := range []struct { + name, extra string + wantNote bool + }{ + {"unset", "", true}, + {"zero", "max_retries: 0\n", false}, + {"set", "max_retries: 2\n", false}, + } { + t.Run(tc.name, func(t *testing.T) { + path := writeConfigFile(t, "run.yaml", minimalConfig+tc.extra) + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + cmd := newConvertToDabsCommand() + cmd.SetContext(ctx) + require.NoError(t, cmd.RunE(cmd, []string{path})) + + assert.Contains(t, stderr.String(), "Wrote a Databricks Asset Bundle") + assert.Equal(t, tc.wantNote, strings.Contains(stderr.String(), "does not set max_retries")) + }) + } +} + func TestConvertToDabsRejectsUnsupported(t *testing.T) { t.Run("usage_policy_name", func(t *testing.T) { cfg := minimalConfig + "usage_policy_name: my-policy\n"