Skip to content

Commit d4a79f8

Browse files
authored
Improve errors for workspace commands against account console hosts (#5506)
## 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 list` fails 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. 1. 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.Execute` appends a note via the new `auth.AppendAccountHostHint`: ``` Note: profile "acc" points to a Databricks account console host (https://accounts.cloud.databricks.com), which serves only account-level APIs. Workspace commands need a workspace host: run `databricks auth login --host https://<workspace-url>`, or use `databricks account ...` commands with this profile ``` 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. Adds `cmdctx.HasWorkspaceClient` as the non-panicking lookup. 2. 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 suggests `databricks auth login --host https://<workspace-url>` or `databricks account ...` commands, instead of the impossible "set workspace_id to a real ID" advice. Other hosts (SPOG/unified) keep the existing wording, and `MustAnyClient` still matches the type to fall through to the account client. ## Test plan - [x] Unit tests for both `AppendAccountHostHint` message variants (profile and no profile), the non-account-host and empty-host passthroughs, error chain preservation, and composition with `EnrichAuthError` (libs/auth) - [x] Table-driven trigger tests through `Execute`: hint fires for workspace client + account console host; stays silent for workspace host, account client, and no client (cmd/root) - [x] Unit tests for both `ErrAccountOnlyProfile` message variants and host plumb-through via `workspaceClientOrPrompt`, plus the existing `MustAnyClient` fall-through test still passes (cmd/root) - [x] `go test ./cmd/root/... ./libs/auth/... ./libs/cmdctx/...` - [x] `./task fmt-q`, `./task lint-q`, `./task checks` - [x] Manual smoke test with a fake `.databrickscfg`: verified the note on `jobs list`, the new account-only message, and no note on `account groups list` No 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.
1 parent 2c0a2f0 commit d4a79f8

9 files changed

Lines changed: 257 additions & 4 deletions

File tree

‎NEXT_CHANGELOG.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313
* `databricks auth profiles --skip-validate` no longer makes any network calls; the host metadata fetch is skipped along with validation ([#5530](https://github.com/databricks/cli/pull/5530)).
1414

1515

16-
1716
### Bundles
1817
* Set the default `data_security_mode` to `DATA_SECURITY_MODE_AUTO` in bundle templates ([#5452](https://github.com/databricks/cli/pull/5452)).
1918
* Mark vector search index index_subtype as backend_default to prevent drift after deployment ([#5454](https://github.com/databricks/cli/pull/5454)).

‎cmd/root/auth.go‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -79,16 +79,26 @@ func patSPOGNoWorkspaceIDError(profileName string) error {
7979
// client so account-only profiles still describe cleanly.
8080
type ErrAccountOnlyProfile struct {
8181
profileName string
82+
// host is the profile's canonical host name (config.CanonicalHostName);
83+
// IsClassicAccountHost only matches the canonical form.
84+
host string
8285
}
8386

8487
func (e ErrAccountOnlyProfile) Error() string {
88+
// A classic account console host serves no workspace APIs at all, so the
89+
// generic "set workspace_id" advice below can never make workspace
90+
// commands work there; following it is how broken profiles get created
91+
// (https://github.com/databricks/cli/issues/5479).
92+
if auth.IsClassicAccountHost(e.host) {
93+
return fmt.Sprintf("profile %q points to a Databricks account console host (%s), which serves only account-level APIs; this command requires a workspace. Run `databricks auth login --host https://<workspace-url>` to create a workspace profile, or use `databricks account ...` commands with this profile", e.profileName, e.host)
94+
}
8595
return fmt.Sprintf("profile %q has no workspace_id set (account-only); this command requires a workspace. Edit the profile to set workspace_id to a real ID, or pass --profile with a workspace-scoped profile", e.profileName)
8696
}
8797

8898
// accountOnlyProfileError describes why a workspace command can't run against
8999
// a profile that has an account_id but no workspace_id.
90-
func accountOnlyProfileError(profileName string) error {
91-
return ErrAccountOnlyProfile{profileName: profileName}
100+
func accountOnlyProfileError(cfg *config.Config) error {
101+
return ErrAccountOnlyProfile{profileName: cfg.Profile, host: cfg.CanonicalHostName()}
92102
}
93103

94104
func profileFlagValue(cmd *cobra.Command) (string, bool) {
@@ -245,7 +255,7 @@ func workspaceClientOrPrompt(ctx context.Context, cfg *config.Config, allowPromp
245255
// can recognize ErrAccountOnlyProfile and fall through to the account
246256
// client; the PAT-on-SPOG check below handles the remaining cases
247257
// (env-var-only configs and profiles without account_id resolved).
248-
return nil, accountOnlyProfileError(cfg.Profile)
258+
return nil, accountOnlyProfileError(cfg)
249259
}
250260
if err == nil && isPATOnSPOGWithoutWorkspaceID(cfg) {
251261
// PATs are workspace-scoped. On a SPOG host without workspace_id the

‎cmd/root/auth_test.go‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -549,6 +549,57 @@ func TestWorkspaceClientOrPromptRejectsAccountOnlyProfile(t *testing.T) {
549549
}
550550
}
551551

552+
func TestErrAccountOnlyProfileMessage(t *testing.T) {
553+
tests := []struct {
554+
name string
555+
err ErrAccountOnlyProfile
556+
want string
557+
}{
558+
{
559+
name: "account console host",
560+
err: ErrAccountOnlyProfile{profileName: "acc", host: "https://accounts.test"},
561+
want: "profile \"acc\" points to a Databricks account console host (https://accounts.test), which serves only account-level APIs; " +
562+
"this command requires a workspace. Run `databricks auth login --host https://<workspace-url>` to create a workspace profile, " +
563+
"or use `databricks account ...` commands with this profile",
564+
},
565+
{
566+
// On non-account-console hosts (SPOG/unified) workspace APIs are
567+
// served, so setting workspace_id is still the right fix.
568+
name: "other host keeps workspace_id advice",
569+
err: ErrAccountOnlyProfile{profileName: "spog", host: "https://unified.test"},
570+
want: "profile \"spog\" has no workspace_id set (account-only); this command requires a workspace. " +
571+
"Edit the profile to set workspace_id to a real ID, or pass --profile with a workspace-scoped profile",
572+
},
573+
}
574+
for _, tt := range tests {
575+
t.Run(tt.name, func(t *testing.T) {
576+
assert.Equal(t, tt.want, tt.err.Error())
577+
})
578+
}
579+
}
580+
581+
func TestWorkspaceClientOrPromptAccountOnlyProfileOnAccountConsoleHost(t *testing.T) {
582+
testutil.CleanupEnvironment(t)
583+
t.Setenv("PATH", "")
584+
585+
cfg := &config.Config{
586+
Host: "https://accounts.test/",
587+
AccountID: "abc-123",
588+
Token: "foobar",
589+
Profile: "acc",
590+
HTTPTransport: noNetworkTransport,
591+
}
592+
593+
w, err := workspaceClientOrPrompt(t.Context(), cfg, false)
594+
assert.Nil(t, w)
595+
require.Error(t, err)
596+
var accountOnly ErrAccountOnlyProfile
597+
require.ErrorAs(t, err, &accountOnly)
598+
assert.Contains(t, err.Error(), "account console host (https://accounts.test)")
599+
assert.Contains(t, err.Error(), "databricks auth login --host")
600+
assert.NotContains(t, err.Error(), "set workspace_id to a real ID")
601+
}
602+
552603
func TestWorkspaceClientOrPromptRejectsPATOnSPOGWithoutWorkspaceID(t *testing.T) {
553604
testutil.CleanupEnvironment(t)
554605
t.Setenv("PATH", "")

‎cmd/root/root.go‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,12 @@ Stack Trace:
149149
cfg := cmdctx.ConfigUsed(cmd.Context())
150150
err = auth.EnrichAuthError(cmd.Context(), cfg, err)
151151
}
152+
// A workspace client on the context means the command operates against
153+
// a workspace; see AppendAccountHostHint for why every error from such
154+
// commands gets the account-console-host note.
155+
if cmdctx.HasWorkspaceClient(cmd.Context()) {
156+
err = auth.AppendAccountHostHint(cmdctx.WorkspaceClient(cmd.Context()).Config, err)
157+
}
152158
fmt.Fprintf(cmd.ErrOrStderr(), "Error: %s\n", err.Error())
153159
}
154160

‎cmd/root/root_test.go‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,12 @@ package root
22

33
import (
44
"bytes"
5+
"context"
6+
"errors"
57
"testing"
68

79
"github.com/databricks/cli/libs/cmdctx"
10+
"github.com/databricks/databricks-sdk-go"
811
"github.com/databricks/databricks-sdk-go/apierr"
912
"github.com/databricks/databricks-sdk-go/config"
1013
"github.com/spf13/cobra"
@@ -77,6 +80,85 @@ func TestExecuteNoEnrichmentWithoutConfigUsed(t *testing.T) {
7780
assert.NotContains(t, output, "Next steps:")
7881
}
7982

83+
func TestExecuteAppendsAccountHostHint(t *testing.T) {
84+
tests := []struct {
85+
name string
86+
setup func(ctx context.Context) context.Context
87+
wantHint bool
88+
}{
89+
{
90+
name: "workspace client on account console host",
91+
setup: func(ctx context.Context) context.Context {
92+
cfg := &config.Config{Host: "https://accounts.test", Profile: "acc"}
93+
ctx = cmdctx.SetConfigUsed(ctx, cfg)
94+
return cmdctx.SetWorkspaceClient(ctx, &databricks.WorkspaceClient{Config: cfg})
95+
},
96+
wantHint: true,
97+
},
98+
{
99+
name: "workspace client on workspace host",
100+
setup: func(ctx context.Context) context.Context {
101+
cfg := &config.Config{Host: "https://adb-123.test", Profile: "ws"}
102+
ctx = cmdctx.SetConfigUsed(ctx, cfg)
103+
return cmdctx.SetWorkspaceClient(ctx, &databricks.WorkspaceClient{Config: cfg})
104+
},
105+
wantHint: false,
106+
},
107+
{
108+
// `databricks account ...` commands configure an account client,
109+
// not a workspace client, so the hint must stay silent.
110+
name: "account client on account console host",
111+
setup: func(ctx context.Context) context.Context {
112+
cfg := &config.Config{Host: "https://accounts.test", Profile: "acc"}
113+
ctx = cmdctx.SetConfigUsed(ctx, cfg)
114+
return cmdctx.SetAccountClient(ctx, &databricks.AccountClient{Config: cfg})
115+
},
116+
wantHint: false,
117+
},
118+
{
119+
name: "no client on account console host",
120+
setup: func(ctx context.Context) context.Context {
121+
cfg := &config.Config{Host: "https://accounts.test", Profile: "acc"}
122+
return cmdctx.SetConfigUsed(ctx, cfg)
123+
},
124+
wantHint: false,
125+
},
126+
}
127+
128+
for _, tt := range tests {
129+
t.Run(tt.name, func(t *testing.T) {
130+
stderr := &bytes.Buffer{}
131+
cmd := &cobra.Command{
132+
Use: "test",
133+
SilenceUsage: true,
134+
SilenceErrors: true,
135+
RunE: func(cmd *cobra.Command, args []string) error {
136+
// The account console returns unstructured junk for
137+
// workspace API paths; this is one real example.
138+
return errors.New("received HTML response instead of JSON")
139+
},
140+
}
141+
cmd.SetErr(stderr)
142+
cmd.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
143+
cmd.SetContext(tt.setup(cmd.Context()))
144+
return nil
145+
}
146+
147+
err := Execute(t.Context(), cmd)
148+
require.Error(t, err)
149+
150+
output := stderr.String()
151+
assert.Contains(t, output, "received HTML response instead of JSON")
152+
if tt.wantHint {
153+
assert.Contains(t, output, "account console host")
154+
assert.Contains(t, output, "databricks auth login --host")
155+
} else {
156+
assert.NotContains(t, output, "account console host")
157+
}
158+
})
159+
}
160+
}
161+
80162
func TestExecuteErrAlreadyPrintedNotEnriched(t *testing.T) {
81163
ctx := t.Context()
82164
stderr := &bytes.Buffer{}

‎libs/auth/error.go‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,27 @@ func EnrichAuthError(ctx context.Context, cfg *config.Config, err error) error {
112112
return fmt.Errorf("%w\n%s", err, b.String())
113113
}
114114

115+
// AppendAccountHostHint appends a note to errors from commands that ran with a
116+
// workspace client configured against a classic account console host. Such
117+
// hosts serve only account-level APIs, so a workspace command can never
118+
// succeed there and the note is relevant for any error. The console's
119+
// responses to workspace API paths are unstructured (HTML pages, bare-string
120+
// 400s), so there is no reliable way to detect "this API is not served here"
121+
// from the error itself; callers gate on the command type instead.
122+
func AppendAccountHostHint(cfg *config.Config, err error) error {
123+
host := cfg.CanonicalHostName()
124+
if !IsClassicAccountHost(host) {
125+
return err
126+
}
127+
subject := "this configuration"
128+
scope := ""
129+
if cfg.Profile != "" {
130+
subject = fmt.Sprintf("profile %q", cfg.Profile)
131+
scope = " with this profile"
132+
}
133+
return fmt.Errorf("%w\n\nNote: %s points to a Databricks account console host (%s), which serves only account-level APIs.\nWorkspace commands need a workspace host: run `databricks auth login --host https://<workspace-url>`, or use `databricks account ...` commands%s", err, subject, host, scope)
134+
}
135+
115136
// writeReauthSteps writes auth-type-aware re-authentication suggestions for 401 errors.
116137
func writeReauthSteps(ctx context.Context, cfg *config.Config, b *strings.Builder) {
117138
switch strings.ToLower(cfg.AuthType) {

‎libs/auth/error_test.go‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ package auth
22

33
import (
44
"errors"
5+
"strings"
56
"testing"
67

78
"github.com/databricks/databricks-sdk-go/apierr"
@@ -260,3 +261,67 @@ func TestEnrichAuthError(t *testing.T) {
260261
})
261262
}
262263
}
264+
265+
func TestAppendAccountHostHint(t *testing.T) {
266+
tests := []struct {
267+
name string
268+
cfg *config.Config
269+
want string
270+
}{
271+
{
272+
name: "account console host with profile",
273+
cfg: &config.Config{Host: "https://accounts.test", Profile: "acc"},
274+
want: "base error\n\n" +
275+
"Note: profile \"acc\" points to a Databricks account console host (https://accounts.test), which serves only account-level APIs.\n" +
276+
"Workspace commands need a workspace host: run `databricks auth login --host https://<workspace-url>`, or use `databricks account ...` commands with this profile",
277+
},
278+
{
279+
name: "account console host without profile",
280+
cfg: &config.Config{Host: "https://accounts.test"},
281+
want: "base error\n\n" +
282+
"Note: this configuration points to a Databricks account console host (https://accounts.test), which serves only account-level APIs.\n" +
283+
"Workspace commands need a workspace host: run `databricks auth login --host https://<workspace-url>`, or use `databricks account ...` commands",
284+
},
285+
{
286+
name: "workspace host is left unchanged",
287+
cfg: &config.Config{Host: "https://adb-123.test", Profile: "ws"},
288+
want: "base error",
289+
},
290+
{
291+
name: "empty host is left unchanged",
292+
cfg: &config.Config{},
293+
want: "base error",
294+
},
295+
}
296+
for _, tt := range tests {
297+
t.Run(tt.name, func(t *testing.T) {
298+
result := AppendAccountHostHint(tt.cfg, errors.New("base error"))
299+
assert.Equal(t, tt.want, result.Error())
300+
})
301+
}
302+
}
303+
304+
func TestAppendAccountHostHintPreservesErrorChain(t *testing.T) {
305+
cfg := &config.Config{Host: "https://accounts.test", Profile: "acc"}
306+
original := &apierr.APIError{StatusCode: 400, Message: "Unable to load OAuth Config"}
307+
308+
result := AppendAccountHostHint(cfg, original)
309+
310+
var unwrapped *apierr.APIError
311+
require.ErrorAs(t, result, &unwrapped)
312+
assert.Equal(t, 400, unwrapped.StatusCode)
313+
}
314+
315+
func TestAppendAccountHostHintComposesWithEnrichAuthError(t *testing.T) {
316+
cfg := &config.Config{Host: "https://accounts.test", Profile: "acc", AuthType: AuthTypePat}
317+
original := &apierr.APIError{StatusCode: 403, Message: "permission denied"}
318+
319+
// Same composition order as cmd/root.Execute: enrichment first, hint last.
320+
result := AppendAccountHostHint(cfg, EnrichAuthError(t.Context(), cfg, original))
321+
322+
msg := result.Error()
323+
assert.Contains(t, msg, "permission denied")
324+
assert.Contains(t, msg, "Next steps:")
325+
assert.Contains(t, msg, "Note: profile \"acc\" points to a Databricks account console host")
326+
assert.Less(t, strings.Index(msg, "Next steps:"), strings.Index(msg, "Note:"))
327+
}

‎libs/cmdctx/workspace_client.go‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,9 @@ func WorkspaceClient(ctx context.Context) *databricks.WorkspaceClient {
2020
}
2121
return v.(*databricks.WorkspaceClient)
2222
}
23+
24+
// HasWorkspaceClient reports whether a workspace client was configured on the
25+
// context via SetWorkspaceClient.
26+
func HasWorkspaceClient(ctx context.Context) bool {
27+
return ctx.Value(workspaceClientKey) != nil
28+
}

‎libs/cmdctx/workspace_client_test.go‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,16 @@ func TestCommandWorkspaceClient(t *testing.T) {
3636
cmdctx.SetWorkspaceClient(ctx, client)
3737
})
3838
}
39+
40+
func TestHasWorkspaceClient(t *testing.T) {
41+
ctx := t.Context()
42+
assert.False(t, cmdctx.HasWorkspaceClient(ctx))
43+
44+
client := &databricks.WorkspaceClient{
45+
Config: &config.Config{
46+
Host: "https://test.test",
47+
},
48+
}
49+
ctx = cmdctx.SetWorkspaceClient(ctx, client)
50+
assert.True(t, cmdctx.HasWorkspaceClient(ctx))
51+
}

0 commit comments

Comments
 (0)