Add verbose error guidance to AIR commands by ben-hansen-db · Pull Request #6522 · databricks/cli

ben-hansen-db · 2026-09-03T22:37:14Z

Changes

Add failed-command guidance entirely within the experimental AIR command package.
Tell users to rerun failed AIR commands with the existing global --debug flag for detailed diagnostics and a stack trace.
Omit the guidance when debug logging is already enabled.

Why

AIR failures currently do not point users to the diagnostics needed to understand the underlying error. The Databricks CLI already uses --debug for detailed logging, while root -v prints the CLI version, so this change uses the existing flag without adding an AIR-specific alias or modifying shared root-command behavior.

Suggested retry commands include only the command path and an ellipsis, so user arguments are not repeated in the error output.

Tests

go test ./experimental/air/cmd
./task lint-q

Both commands passed.

eng-dev-ecosystem-bot · 2026-09-03T22:55:58Z

Integration test report

Commit: 755025d

Run: 33904955583

	Env	✅pass	🙈skip	Time
✅	aws linux	276	19	5:57
✅	aws windows	278	17	4:05
✅	azure linux	275	19	8:20
✅	azure windows	277	17	4:31
✅	gcp linux	276	19	8:02
✅	gcp windows	278	17	5:42

Top 6 slowest tests (at least 2 minutes):

duration	env	testname
4:29	azure windows	TestAccept
4:13	gcp windows	TestAccept
4:02	aws windows	TestAccept
3:48	azure linux	TestAccept
3:47	aws linux	TestAccept
3:38	gcp linux	TestAccept

eng-dev-ecosystem-bot · 2026-09-05T00:55:17Z

Integration test report

Commit: fb4da64

Run: 33908289087

	Env	❌FAIL	🟨KNOWN	🤯MISS	🔄flaky	💚RECOVERED	🙈SKIP	✅pass	🙈skip	Time
❌	aws linux	18	1				1	1500	988	322:12
❌	aws windows	16		17			1	1394	1009	348:44
💚	azure linux					1	1	1343	1034	178:15
🔄	azure windows				2	1	1	1247	1057	187:19
🔄	gcp linux				3		1	1327	1038	213:53
🔄	gcp windows				3		1	1233	1061	213:51

47 interesting tests: 23 FAIL, 16 MISS, 6 flaky, 1 KNOWN, 1 SKIP

	Test Name	aws linux	aws windows	azure linux	azure windows	gcp linux	gcp windows
🟨	TestAccept	🟨K	🤯M	💚R	💚R	🔄f	🔄f
❌	TestAccept/bundle/deploy/spark-jar-task	✅p	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/deploy/spark-jar-task/DATABRICKS_BUNDLE_ENGINE=terraform/DMS=	✅p	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/invariant/delete_idempotent	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/invariant/delete_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=1	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/invariant/delete_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=	✅p	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/invariant/delete_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1	❌F	✅p	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/invariant/destroy_idempotent	❌F	✅p	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/invariant/destroy_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=	❌F	✅p	✅p	✅p	✅p	✅p
🤯	TestAccept/bundle/invariant/no_drift	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=	✅p	🤯M	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/deploy/data_security_mode	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/deploy/data_security_mode/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/deploy/simple	✅p	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/deploy/simple/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true	✅p	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/deploy/update-after-create	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/deploy/update-after-create/DATABRICKS_BUNDLE_ENGINE=terraform/DMS=	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/lifecycle-started	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/resize-terminated-fallback	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/resize-terminated-fallback/DATABRICKS_BUNDLE_ENGINE=direct/DMS=	❌F	❌F	✅p	✅p	✅p	✅p
❌	TestAccept/bundle/resources/clusters/resize-terminated-fallback/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true	❌F	✅p	✅p	✅p	✅p	✅p
🔄	TestAccept/bundle/resources/job_runs/failed_run	✅p	✅p	✅p	✅p	🔄f	✅p
🔄	TestAccept/bundle/resources/job_runs/failed_run/DATABRICKS_BUNDLE_ENGINE=direct/DMS=	✅p	✅p	✅p	✅p	🔄f	✅p
❌	TestAccept/bundle/resources/postgres_synced_tables/recreate	❌F	✅p	🙈s	🙈s	🙈s	🙈s
❌	TestAccept/bundle/resources/postgres_synced_tables/recreate/DATABRICKS_BUNDLE_ENGINE=direct/DMS=	❌F	✅p
❌	TestAccept/bundle/resources/postgres_synced_tables/recreate/DATABRICKS_BUNDLE_ENGINE=terraform/DMS=	❌F	✅p
🔄	TestAccept/bundle/resources/vector_search_endpoints/drift/recreated_same_name	✅p	✅p	✅p	✅p	✅p	🔄f
🔄	TestAccept/bundle/resources/vector_search_endpoints/drift/recreated_same_name/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true	✅p	✅p	✅p	✅p	✅p	🔄f
🙈	TestAccept/ssh/connection	🙈S	🙈S	🙈S	🙈S	🙈S	🙈S
🤯	TestCIUniqueName	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestDbrAcceptance	🙈s	🤯M	🙈s	🙈s	🙈s	🙈s
🤯	TestInprocessMode	🙈s	🤯M	🙈s	🙈s	🙈s	🙈s
🤯	TestInvariantConfigsCoverage	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetApproximatesPct	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetChangedAlwaysRuns	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetChangedVariantFilter	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetChangedVariantFilterAlternatives	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetDisabled	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetPctBoundaries	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetSeedChangesSelection	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetSeedDeterministic	✅p	🤯M	✅p	✅p	✅p	✅p
🤯	TestSubsetVariantsIndependent	✅p	🤯M	✅p	✅p	✅p	✅p
🔄	TestFsCpDirToDirFileNotOverwritten	✅p	✅p	✅p	🔄f	✅p	✅p
🔄	TestFsCpDirToDirFileNotOverwritten/uc-volumes_to_uc-volumes	✅p	✅p	✅p	🔄f	✅p	✅p

Top 50 slowest tests (at least 2 minutes):

duration	env	testname
42:44	aws linux	TestAccept/bundle/deploy/spark-jar-task/DATABRICKS_BUNDLE_ENGINE=terraform/DMS=
39:11	aws windows	TestAccept/bundle/deploy/spark-jar-task/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
39:04	aws linux	TestAccept/bundle/deploy/spark-jar-task/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
28:31	aws windows	TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
26:34	aws windows	TestAccept/bundle/resources/clusters/resize-terminated-fallback/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
25:07	aws windows	TestAccept/bundle/invariant/delete_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
22:44	aws linux	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
20:36	aws linux	TestAccept/bundle/invariant/delete_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=
20:30	aws linux	TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
19:20	aws windows	TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
19:02	aws linux	TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
18:49	aws linux	TestAccept/bundle/invariant/destroy_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
16:35	aws windows	TestAccept/bundle/resources/clusters/deploy/update-after-create/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
16:35	aws linux	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
16:12	aws windows	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
15:33	aws windows	TestAccept/bundle/resources/clusters/deploy/data_security_mode/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
15:18	aws windows	TestAccept/bundle/resources/clusters/deploy/update-after-create/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
15:01	aws windows	TestAccept/bundle/deploy/spark-jar-task/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
14:22	gcp windows	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
14:17	gcp linux	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
14:09	gcp windows	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
14:09	aws linux	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=
13:34	gcp linux	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
13:01	aws linux	TestAccept/bundle/resources/clusters/deploy/update-after-create/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
12:17	aws linux	TestAccept/bundle/invariant/destroy_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=1
12:04	aws linux	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
11:35	aws windows	TestAccept/bundle/invariant/destroy_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
11:20	aws windows	TestAccept/bundle/invariant/destroy_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
10:47	aws linux	TestAccept/bundle/resources/clusters/deploy/simple/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
9:39	gcp linux	TestAccept/bundle/resources/clusters/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
9:30	azure linux	TestAccept/bundle/resources/clusters/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
8:52	gcp linux	TestAccept/bundle/resources/clusters/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
8:41	aws windows	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
8:34	aws linux	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
8:33	aws linux	TestAccept/bundle/deploy/spark-jar-task/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
8:20	gcp windows	TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
8:15	azure linux	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
8:13	aws windows	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
8:09	gcp windows	TestAccept/bundle/resources/clusters/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
8:03	aws linux	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
8:01	aws linux	TestAccept/bundle/resources/clusters/deploy/simple/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
8:00	aws windows	TestAccept/bundle/invariant/destroy_idempotent/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=1
7:52	gcp linux	TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
7:51	aws windows	TestAccept/bundle/resources/clusters/deploy/simple/DATABRICKS_BUNDLE_ENGINE=direct/DMS=
7:51	azure windows	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
7:50	aws linux	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=
7:42	azure linux	TestAccept/bundle/resources/apps/lifecycle-started/DATABRICKS_BUNDLE_ENGINE=direct/DMS=true
7:40	aws windows	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=
7:26	aws linux	TestAccept/bundle/invariant/no_drift/DATABRICKS_BUNDLE_ENGINE=direct/DMS=/INPUT_CONFIG=cluster.yml.tmpl/READPLAN=1
7:20	aws linux	TestAccept/bundle/resources/clusters/deploy/data_security_mode/DATABRICKS_BUNDLE_ENGINE=direct/DMS=

Add verbose error guidance to AIR commands

61f9844

ben-hansen-db marked this pull request as draft September 3, 2026 22:37

ben-hansen-db added 2 commits September 3, 2026 23:28

Use debug flag for Databricks CLI diagnostics

9f23032

Scope error guidance to AIR commands

fe34f8f

ben-hansen-db requested a review from vinchenzo-db September 3, 2026 23:46

ben-hansen-db marked this pull request as ready for review September 3, 2026 23:46

vinchenzo-db approved these changes Sep 4, 2026

View reviewed changes

ben-hansen-db added 2 commits September 4, 2026 16:24

Update AIR acceptance outputs

b4e81ed

Limit AIR debug tip to submission commands

755025d

ben-hansen-db enabled auto-merge September 4, 2026 18:27

ben-hansen-db added this pull request to the merge queue Sep 4, 2026

Merged via the queue into main with commit fb4da64 Sep 4, 2026
32 checks passed

ben-hansen-db deleted the ben-hansen_data/ben/cli-verbose-error-tip branch September 4, 2026 18:52

Navigation Menu

Uh oh!

Add verbose error guidance to AIR commands - #6522

Add verbose error guidance to AIR commands#6522
ben-hansen-db merged 5 commits into
mainfrom
ben-hansen_data/ben/cli-verbose-error-tip

ben-hansen-db commented Sep 3, 2026 •

edited

Loading

Uh oh!

eng-dev-ecosystem-bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

eng-dev-ecosystem-bot commented Sep 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

ben-hansen-db commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Why

Tests

Uh oh!

eng-dev-ecosystem-bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Integration test report

Uh oh!

Uh oh!

eng-dev-ecosystem-bot commented Sep 5, 2026

Integration test report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ben-hansen-db commented Sep 3, 2026 •

edited

Loading

eng-dev-ecosystem-bot commented Sep 3, 2026 •

edited

Loading