Enrich 401/403 errors with auth identity context (#4576)

## Why

When CLI commands fail with 401 (unauthorized) or 403 (forbidden), the
error message shows only the raw API error (e.g., `PERMISSION_DENIED:
...`) with no indication of which profile, host, or auth method was
used. This makes debugging auth issues unnecessarily difficult — the
first thing users and support ask is "which identity am I using?"

## Changes

- **`libs/auth/error.go`** — New `EnrichAuthError` function that detects
`apierr.APIError` with status 401 or 403 and appends:
  - Identity context: profile, host, auth type (each omitted if empty)
- Auth-type-aware remediation steps (OAuth → `auth login`, PAT →
regenerate token, Azure CLI → `az login`, M2M → check credentials, etc.)
- `auth describe` command with correct flags for
workspace/account/unified contexts (including `--workspace-id`)
  - Profile nudge when using env-var-based auth
- **`libs/auth/error.go`** — New `BuildDescribeCommand` that builds
`databricks auth describe` flags directly from `*config.Config` (avoids
information loss from OAuthArgument conversion, e.g., workspace-id)
- **`cmd/root/root.go`** — Call `EnrichAuthError` in the centralized
`Execute` error path, gated on `cmdctx.HasConfigUsed`. Covers both
client creation errors (PersistentPreRunE) and command execution errors
(RunE)
- **`acceptance/workspace/jobs/create-error/output.txt`** — Regenerated
golden file

### Scope limitations

Commands that bypass `MustWorkspaceClient`/`MustAccountClient` and don't
call `SetConfigUsed` (e.g., `databricks api`) won't get enrichment. This
can be addressed in a follow-up.

### Example output

<img width="1354" height="173" alt="image"
src="https://github.com/user-attachments/assets/901687e6-d7dc-4837-9715-bb1405bd1280"
/>



https://github.com/user-attachments/assets/2fa2445f-c15b-4dfa-b785-255c4e621f6d


**403 with profile:**
```
Error: PERMISSION_DENIED: User does not have permission.

Profile:   my-profile
Host:      https://myworkspace.cloud.databricks.com
Auth type: pat

Next steps:
  - Verify you have the required permissions for this operation
  - Check your identity: databricks auth describe --profile my-profile
```

**401 without profile (env var auth):**
```
Error: UNAUTHENTICATED: Token expired.

Host:      https://myworkspace.cloud.databricks.com
Auth type: pat

Next steps:
  - Regenerate your access token
  - Check your identity: databricks auth describe --host https://myworkspace.cloud.databricks.com
  - Consider configuring a profile: databricks configure --profile <name>
```

## Test plan

### Automated
- [x] `go test ./libs/auth/...` — unit tests for `EnrichAuthError`,
`BuildDescribeCommand`, error preservation, all auth types, unified host
workspace-id
- [x] `go test ./cmd/root/...` — integration tests for Execute wiring
(with ConfigUsed, without, ErrAlreadyPrinted)
- [x] `go test ./acceptance -run TestAccept/workspace/jobs/create-error`
— acceptance test with updated golden file
- [x] `make checks` — whitespace, tidy, links

### Manual testing

**Force a 401 (expired/invalid token):**
```bash
# Option A: Set a bogus token via env vars (no profile)
DATABRICKS_HOST=https://<your-workspace>.cloud.databricks.com \
DATABRICKS_TOKEN=invalid-token-abc123 \
/tmp/databricks-test clusters list

# Option B: Create a profile with a bad token
cat >> ~/.databrickscfg << 'EOF'

[bad-token-test]
host = https://<your-workspace>.cloud.databricks.com
token = dapi_invalid_token_for_testing
EOF

/tmp/databricks-test clusters list --profile bad-token-test

# Clean up after:
# Remove the [bad-token-test] section from ~/.databrickscfg
```

**Verify non-auth errors are unaffected:**
```bash
# A 404 should show no enrichment:
/tmp/databricks-test clusters get --cluster-id nonexistent-id --profile <your-profile>
```

Author: simonfaltum

acceptance/workspace/jobs/create-error/output.txt

@@ -2,4 +2,12 @@
 >>> [CLI] jobs create --json {"name":"abc"}
 Error: Invalid access token.
 
+Host:      [DATABRICKS_URL]
+Auth type: Personal Access Token (pat)
+
+Next steps:
+  - Verify you have the required permissions for this operation
+  - Check your identity: databricks auth describe
+  - Consider configuring a profile: databricks configure --profile <name>
+
 Exit code: 1

cmd/root/root.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/databricks/cli/internal/build"
 	"github.com/databricks/cli/libs/agent"
+	"github.com/databricks/cli/libs/auth"
 	"github.com/databricks/cli/libs/cmdctx"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/databricks/cli/libs/dbr"
@@ -147,6 +148,10 @@ Stack Trace:
 	// Run the command
 	cmd, err = cmd.ExecuteContextC(ctx)
 	if err != nil && !errors.Is(err, ErrAlreadyPrinted) {
+		if cmdctx.HasConfigUsed(cmd.Context()) {
+			cfg := cmdctx.ConfigUsed(cmd.Context())
+			err = auth.EnrichAuthError(cmd.Context(), cfg, err)
+		}
 		fmt.Fprintf(cmd.ErrOrStderr(), "Error: %s\n", err.Error())
 	}
 

cmd/root/root_test.go

@@ -0,0 +1,98 @@
+package root
+
+import (
+	"bytes"
+	"context"
+	"testing"
+
+	"github.com/databricks/cli/libs/cmdctx"
+	"github.com/databricks/databricks-sdk-go/apierr"
+	"github.com/databricks/databricks-sdk-go/config"
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestExecuteEnrichesAuthErrors(t *testing.T) {
+	ctx := context.Background()
+	stderr := &bytes.Buffer{}
+
+	cmd := &cobra.Command{
+		Use:           "test",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return &apierr.APIError{
+				StatusCode: 403,
+				ErrorCode:  "PERMISSION_DENIED",
+				Message:    "no access",
+			}
+		},
+	}
+	cmd.SetErr(stderr)
+
+	// Simulate MustWorkspaceClient setting config in context via PersistentPreRunE.
+	cmd.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
+		cfg := &config.Config{
+			Host:     "https://test.cloud.databricks.com",
+			Profile:  "test-profile",
+			AuthType: "pat",
+		}
+		ctx := cmdctx.SetConfigUsed(cmd.Context(), cfg)
+		cmd.SetContext(ctx)
+		return nil
+	}
+
+	err := Execute(ctx, cmd)
+	require.Error(t, err)
+
+	output := stderr.String()
+	assert.Contains(t, output, "no access")
+	assert.Contains(t, output, "Next steps:")
+}
+
+func TestExecuteNoEnrichmentWithoutConfigUsed(t *testing.T) {
+	ctx := context.Background()
+	stderr := &bytes.Buffer{}
+
+	cmd := &cobra.Command{
+		Use:           "test",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return &apierr.APIError{
+				StatusCode: 403,
+				ErrorCode:  "PERMISSION_DENIED",
+				Message:    "no access",
+			}
+		},
+	}
+	cmd.SetErr(stderr)
+
+	err := Execute(ctx, cmd)
+	require.Error(t, err)
+
+	output := stderr.String()
+	assert.Contains(t, output, "no access")
+	assert.NotContains(t, output, "Profile:")
+	assert.NotContains(t, output, "Next steps:")
+}
+
+func TestExecuteErrAlreadyPrintedNotEnriched(t *testing.T) {
+	ctx := context.Background()
+	stderr := &bytes.Buffer{}
+
+	cmd := &cobra.Command{
+		Use:           "test",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return ErrAlreadyPrinted
+		},
+	}
+	cmd.SetErr(stderr)
+
+	err := Execute(ctx, cmd)
+	require.Error(t, err)
+	assert.Empty(t, stderr.String())
+}

libs/auth/error.go

@@ -3,11 +3,54 @@ package auth
 import (
 	"context"
 	"errors"
+	"fmt"
+	"net/http"
 	"strings"
 
+	"github.com/databricks/databricks-sdk-go/apierr"
+	"github.com/databricks/databricks-sdk-go/config"
 	"github.com/databricks/databricks-sdk-go/credentials/u2m"
 )
 
+// Auth type names returned by credential providers.
+const (
+	AuthTypeDatabricksCli   = "databricks-cli"
+	AuthTypePat             = "pat"
+	AuthTypeBasic           = "basic"
+	AuthTypeAzureCli        = "azure-cli"
+	AuthTypeOAuthM2M        = "oauth-m2m"
+	AuthTypeAzureMSI        = "azure-msi"
+	AuthTypeAzureSecret     = "azure-client-secret"
+	AuthTypeGoogleCreds     = "google-credentials"
+	AuthTypeGoogleID        = "google-id"
+	AuthTypeGitHubOIDC      = "github-oidc-azure"
+	AuthTypeMetadataService = "metadata-service"
+)
+
+// authTypeDisplayNames maps auth type identifiers to human-readable names.
+var authTypeDisplayNames = map[string]string{
+	AuthTypeDatabricksCli:   "OAuth (databricks-cli)",
+	AuthTypePat:             "Personal Access Token (pat)",
+	AuthTypeBasic:           "Basic",
+	AuthTypeAzureCli:        "Azure CLI (azure-cli)",
+	AuthTypeOAuthM2M:        "OAuth Machine-to-Machine (oauth-m2m)",
+	AuthTypeAzureMSI:        "Azure Managed Identity (azure-msi)",
+	AuthTypeAzureSecret:     "Azure Client Secret (azure-client-secret)",
+	AuthTypeGoogleCreds:     "Google Credentials (google-credentials)",
+	AuthTypeGoogleID:        "Google Default Credentials (google-id)",
+	AuthTypeGitHubOIDC:      "GitHub OIDC for Azure (github-oidc-azure)",
+	AuthTypeMetadataService: "Metadata Service (metadata-service)",
+}
+
+// AuthTypeDisplayName returns a human-readable name for the given auth type.
+// Falls back to the raw identifier if no display name is registered.
+func AuthTypeDisplayName(authType string) string {
+	if name, ok := authTypeDisplayNames[strings.ToLower(authType)]; ok {
+		return name
+	}
+	return authType
+}
+
 // RewriteAuthError rewrites the error message for invalid refresh token error.
 // It returns whether the error was rewritten and the rewritten error.
 func RewriteAuthError(ctx context.Context, host, accountId, profile string, err error) (bool, error) {
@@ -27,6 +70,102 @@ func RewriteAuthError(ctx context.Context, host, accountId, profile string, err
 	return false, err
 }
 
+// EnrichAuthError appends identity context and remediation steps to 401/403 API errors.
+// For non-API errors or other status codes, the original error is returned unchanged.
+func EnrichAuthError(ctx context.Context, cfg *config.Config, err error) error {
+	var apiErr *apierr.APIError
+	if !errors.As(err, &apiErr) {
+		return err
+	}
+	if apiErr.StatusCode != http.StatusUnauthorized && apiErr.StatusCode != http.StatusForbidden {
+		return err
+	}
+
+	var b strings.Builder
+
+	// Identity context.
+	if cfg.Profile != "" {
+		fmt.Fprintf(&b, "\nProfile:   %s", cfg.Profile)
+	}
+	if cfg.Host != "" {
+		fmt.Fprintf(&b, "\nHost:      %s", cfg.Host)
+	}
+	if cfg.AuthType != "" {
+		fmt.Fprintf(&b, "\nAuth type: %s", AuthTypeDisplayName(cfg.AuthType))
+	}
+
+	fmt.Fprint(&b, "\n\nNext steps:")
+
+	if apiErr.StatusCode == http.StatusUnauthorized {
+		writeReauthSteps(ctx, cfg, &b)
+	} else {
+		fmt.Fprint(&b, "\n  - Verify you have the required permissions for this operation")
+	}
+
+	// Always suggest checking identity.
+	fmt.Fprintf(&b, "\n  - Check your identity: %s", BuildDescribeCommand(cfg))
+
+	// Nudge toward profiles when using env-var-based auth.
+	if cfg.Profile == "" {
+		fmt.Fprint(&b, "\n  - Consider configuring a profile: databricks configure --profile <name>")
+	}
+
+	return fmt.Errorf("%w\n%s", err, b.String())
+}
+
+// writeReauthSteps writes auth-type-aware re-authentication suggestions for 401 errors.
+func writeReauthSteps(ctx context.Context, cfg *config.Config, b *strings.Builder) {
+	switch strings.ToLower(cfg.AuthType) {
+	case AuthTypeDatabricksCli:
+		// When profile is set, BuildLoginCommand uses --profile and ignores
+		// the OAuthArgument, so skip the conversion entirely.
+		if cfg.Profile != "" {
+			fmt.Fprintf(b, "\n  - Re-authenticate: databricks auth login --profile %s", cfg.Profile)
+			return
+		}
+		oauthArg, argErr := AuthArguments{
+			Host:          cfg.Host,
+			AccountID:     cfg.AccountID,
+			WorkspaceID:   cfg.WorkspaceID,
+			IsUnifiedHost: cfg.Experimental_IsUnifiedHost,
+		}.ToOAuthArgument()
+		if argErr != nil {
+			fmt.Fprint(b, "\n  - Re-authenticate: databricks auth login")
+			return
+		}
+		loginCmd := BuildLoginCommand(ctx, "", oauthArg)
+		// For unified hosts, BuildLoginCommand (via OAuthArgument) doesn't carry
+		// workspace-id. Append it so the command is actionable.
+		if cfg.Experimental_IsUnifiedHost && cfg.WorkspaceID != "" {
+			loginCmd += " --workspace-id " + cfg.WorkspaceID
+		}
+		fmt.Fprintf(b, "\n  - Re-authenticate: %s", loginCmd)
+
+	case AuthTypePat:
+		if cfg.Profile != "" {
+			fmt.Fprintf(b, "\n  - Regenerate your access token or run: databricks configure --profile %s", cfg.Profile)
+		} else {
+			fmt.Fprint(b, "\n  - Regenerate your access token")
+		}
+
+	case AuthTypeBasic:
+		if cfg.Profile != "" {
+			fmt.Fprintf(b, "\n  - Check your username/password or run: databricks configure --profile %s", cfg.Profile)
+		} else {
+			fmt.Fprint(b, "\n  - Check your username and password")
+		}
+
+	case AuthTypeAzureCli:
+		fmt.Fprint(b, "\n  - Re-authenticate with Azure: az login")
+
+	case AuthTypeOAuthM2M:
+		fmt.Fprint(b, "\n  - Check your service principal client ID and secret")
+
+	default:
+		fmt.Fprint(b, "\n  - Check your authentication credentials")
+	}
+}
+
 // BuildLoginCommand builds the login command for the given OAuth argument or profile.
 func BuildLoginCommand(ctx context.Context, profile string, arg u2m.OAuthArgument) string {
 	cmd := []string{
@@ -48,3 +187,14 @@ func BuildLoginCommand(ctx context.Context, profile string, arg u2m.OAuthArgumen
 	}
 	return strings.Join(cmd, " ")
 }
+
+// BuildDescribeCommand builds the describe command for the given config.
+// When a profile is set, it uses --profile. Otherwise it emits a bare command
+// since `databricks auth describe` resolves env vars (DATABRICKS_HOST, etc.)
+// automatically.
+func BuildDescribeCommand(cfg *config.Config) string {
+	if cfg.Profile != "" {
+		return "databricks auth describe --profile " + cfg.Profile
+	}
+	return "databricks auth describe"
+}