Improve errors for workspace commands against account console hosts#5506
Merged
Conversation
Classic account console hosts (accounts.cloud.databricks.com etc.) serve only account-level APIs, but their responses to workspace API paths are unstructured junk (HTML pages, bare-string 400s) that cannot be matched reliably. Instead of trying to detect API availability, append a note to any error from a command that ran with a workspace client configured against such a host: workspace commands can never succeed there, so the note is always relevant. Adds cmdctx.HasWorkspaceClient as the non-panicking lookup used to detect that a workspace client was configured on the command context. Co-authored-by: Isaac
The previous message told users to set workspace_id to a real ID. On a classic account console host that advice can never make workspace commands work (the host serves no workspace APIs), and following it is how the broken profiles in #5479 were created. Carry the canonical host on the error and, for account console hosts, point users at a workspace login or account commands instead. Other hosts (SPOG/unified) keep the existing wording, and MustAnyClient still matches the type to fall through to the account client. Co-authored-by: Isaac
Co-authored-by: Isaac
simonfaltum
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
simonfaltum
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
Collaborator
|
Commit: 3e9ccd8
23 interesting tests: 15 SKIP, 7 KNOWN, 1 flaky
Top 29 slowest tests (at least 2 minutes):
|
mihaimitrea-db
approved these changes
Jun 10, 2026
simonfaltum
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
simonfaltum
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Profiles that point at a classic account console host (https://accounts.cloud.databricks.com and friends) only serve account-level APIs. When users run workspace commands against such a profile, the console returns junk and the CLI surfaces it as-is:
databricks jobs listfails with "Error: received HTML response instead of JSON", and other paths return a bare HTTP 400 with "Unable to load OAuth Config". Nothing tells the user the host is the problem.Worse, the existing account-only profile error said "Edit the profile to set workspace_id to a real ID", which can never work on an account console host (it serves no workspace APIs) and is exactly how the broken profiles in the linked issue were created.
These failure shapes are unstructured (HTML pages, bare-string bodies, no error codes), so there is no reliable way to detect "this API is not available here" from the response. Instead, the CLI now adds context based on what it does know: the command operates against a workspace, and the host is an account console host.
Relates to #5479
Changes
Before, workspace commands against an account console host failed with raw junk errors and misleading advice; now the CLI explains the host mismatch and points to a fix.
Failure-time hint: when a command fails and a workspace client was configured on the command context and the host is a classic account console host,
cmd/root.Executeappends a note via the newauth.AppendAccountHostHint:The note fires for any error from such commands (workspace commands can never succeed against these hosts today), composes with the existing 401/403 enrichment, and stays silent for
databricks account ...commands, auth commands, and anything that did not configure a workspace client. Addscmdctx.HasWorkspaceClientas the non-panicking lookup.Host-aware
ErrAccountOnlyProfile: the error now carries the profile's canonical host. For account console hosts it says the host serves only account-level APIs and suggestsdatabricks auth login --host https://<workspace-url>ordatabricks account ...commands, instead of the impossible "set workspace_id to a real ID" advice. Other hosts (SPOG/unified) keep the existing wording, andMustAnyClientstill matches the type to fall through to the account client.Test plan
AppendAccountHostHintmessage variants (profile and no profile), the non-account-host and empty-host passthroughs, error chain preservation, and composition withEnrichAuthError(libs/auth)Execute: hint fires for workspace client + account console host; stays silent for workspace host, account client, and no client (cmd/root)ErrAccountOnlyProfilemessage variants and host plumb-through viaworkspaceClientOrPrompt, plus the existingMustAnyClientfall-through test still passes (cmd/root)go test ./cmd/root/... ./libs/auth/... ./libs/cmdctx/..../task fmt-q,./task lint-q,./task checks.databrickscfg: verified the note onjobs list, the new account-only message, and no note onaccount groups listNo acceptance tests: the hint path needs a live workspace client against a real
accounts.*host, and real domains are forbidden in fixtures; unit coverage exercises the same seams.This pull request and its description were written by Isaac.