Surface notFoundHint message in auth token error path

token.go's loadToken rewrites cache.ErrNotFound to the constant
"cache: databricks OAuth is not configured for this host" so older SDK
versions (pre-v0.77.0) can substring-match the error and fall through
to other auth providers. That rewrite, written before the secure-storage
default, silently threw away the notFoundHintCache message a
default-secure user would see post-upgrade: instead of the actionable
"stored credentials from older CLI versions are no longer used; run
auth login or set DATABRICKS_AUTH_STORAGE=plaintext" copy, they got the
generic "Try logging in again ... If this fails, please report this
issue" trailer, which steers expected upgrade behavior toward bug
reports.

Add storage.HintForNotFound to extract the notFoundHint message from
an error chain, plus storage.NewNotFoundHint as a test factory.
token.go now keeps the SDK-compat substring AND appends the hint when
present, and skips the helpfulError trailer in that case.

Co-authored-by: Isaac

Author: simonfaltum

cmd/auth/token.go

@@ -285,10 +285,22 @@ func loadToken(ctx context.Context, args loadTokenArgs) (*oauth2.Token, error) {
 			//
 			// Older SDK versions check for a particular substring to determine if
 			// the OAuth authentication type can fall through or if it is a real error.
-			// This means we need to keep this error message constant for backwards compatibility.
+			// This means we need to keep "databricks OAuth is not configured for
+			// this host" present in the error for backwards compatibility.
 			//
 			// This is captured in an acceptance test under "cmd/auth/token".
-			err = errors.New("cache: databricks OAuth is not configured for this host")
+			const compatSubstring = "databricks OAuth is not configured for this host"
+			// When storage's notFoundHintCache wrapped the ErrNotFound with
+			// an actionable hint (e.g. the post-upgrade "stored credentials
+			// from older CLI versions are no longer used; run `databricks
+			// auth login`..." copy), surface it instead of the generic
+			// "Try logging in again with ... If this fails, please report
+			// this issue" trailer. The hint is more specific and avoids
+			// users reporting expected post-upgrade behavior as a bug.
+			if hint := storage.HintForNotFound(err); hint != "" {
+				return nil, fmt.Errorf("cache: %s. %s", compatSubstring, hint)
+			}
+			err = errors.New("cache: " + compatSubstring)
 		}
 		if rewritten, rewrittenErr := auth.RewriteAuthError(ctx, args.authArguments.Host, args.authArguments.AccountID, args.profileName, err); rewritten {
 			return nil, rewrittenErr

cmd/auth/token_test.go

@@ -10,15 +10,34 @@ import (
 	"time"
 
 	"github.com/databricks/cli/libs/auth"
+	"github.com/databricks/cli/libs/auth/storage"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/databricks/cli/libs/databrickscfg/profile"
 	"github.com/databricks/cli/libs/env"
 	"github.com/databricks/databricks-sdk-go/credentials/u2m"
+	"github.com/databricks/databricks-sdk-go/credentials/u2m/cache"
 	"github.com/databricks/databricks-sdk-go/httpclient/fixtures"
 	"github.com/stretchr/testify/assert"
 	"golang.org/x/oauth2"
 )
 
+// upgradeHintTokenCache returns a notFoundHint-wrapped ErrNotFound on
+// Lookup, mirroring what storage.notFoundHintCache produces in
+// production when ~/.databricks/token-cache.json has entries and the
+// resolver picked secure mode by default. Used by TestToken_loadToken
+// to verify that auth token surfaces the upgrade-specific hint instead
+// of dropping it for the SDK-compat constant string.
+type upgradeHintTokenCache struct{}
+
+func (upgradeHintTokenCache) Store(string, *oauth2.Token) error { return nil }
+func (upgradeHintTokenCache) Lookup(string) (*oauth2.Token, error) {
+	return nil, storage.NewNotFoundHint(
+		"stored credentials from older CLI versions are no longer used; run `databricks auth login` to sign in again, or set DATABRICKS_AUTH_STORAGE=plaintext to keep using the file cache",
+	)
+}
+
+var _ cache.TokenCache = upgradeHintTokenCache{}
+
 type failOnCallTransport struct{}
 
 func (failOnCallTransport) RoundTrip(*http.Request) (*http.Response, error) {
@@ -408,6 +427,35 @@ func TestToken_loadToken(t *testing.T) {
 				"Try logging in again with `databricks auth login --host https://nonexistent.cloud.databricks.com` before retrying. " +
 				"If this fails, please report this issue to the Databricks CLI maintainers at https://github.com/databricks/cli/issues/new",
 		},
+		{
+			// Regression test: when notFoundHintCache wraps ErrNotFound
+			// with the upgrade copy (post-upgrade default-secure user
+			// with a populated token-cache.json), `auth token` must
+			// surface that hint instead of dropping it for the SDK-compat
+			// constant string. The combined message keeps the
+			// "OAuth is not configured for this host" substring older
+			// SDK versions look for and skips the generic "Try logging
+			// in again ... If this fails, please report this issue"
+			// trailer, which would mislead users into reporting expected
+			// post-upgrade behavior.
+			name: "ErrNotFound carrying upgrade hint surfaces it",
+			args: loadTokenArgs{
+				authArguments: &auth.AuthArguments{},
+				profileName:   "",
+				args:          []string{"nonexistent.cloud.databricks.com"},
+				tokenTimeout:  1 * time.Hour,
+				profiler:      profiler,
+				tokenCache:    upgradeHintTokenCache{},
+				persistentAuthOpts: []u2m.PersistentAuthOption{
+					u2m.WithTokenCache(upgradeHintTokenCache{}),
+					u2m.WithOAuthEndpointSupplier(&MockApiClient{}),
+				},
+			},
+			wantErr: "cache: databricks OAuth is not configured for this host. " +
+				"stored credentials from older CLI versions are no longer used; " +
+				"run `databricks auth login` to sign in again, " +
+				"or set DATABRICKS_AUTH_STORAGE=plaintext to keep using the file cache",
+		},
 		{
 			name: "errors with clear message for non-host non-profile positional arg",
 			args: loadTokenArgs{

libs/auth/storage/not_found_hint.go

@@ -58,6 +58,33 @@ type notFoundHint struct {
 func (e *notFoundHint) Error() string { return e.msg }
 func (e *notFoundHint) Unwrap() error { return cache.ErrNotFound }
 
+// HintForNotFound extracts the actionable hint message from an error
+// chain produced by notFoundHintCache. Returns the empty string if the
+// chain does not contain a notFoundHint (e.g. an unwrapped
+// cache.ErrNotFound from a plain TokenCache).
+//
+// Used by call sites like `auth token` that rewrite the SDK error for
+// backwards-compatibility (the "databricks OAuth is not configured for
+// this host" substring is load-bearing for older SDK fall-through
+// logic) but want to surface the actionable hint to the user instead of
+// dropping it.
+func HintForNotFound(err error) string {
+	var hint *notFoundHint
+	if errors.As(err, &hint) {
+		return hint.msg
+	}
+	return ""
+}
+
+// NewNotFoundHint returns an error that renders as msg but unwraps to
+// cache.ErrNotFound, mirroring what notFoundHintCache produces in
+// production. Exported so tests in other packages (e.g. cmd/auth) can
+// construct a hint-wrapped error without going through the full
+// resolver setup.
+func NewNotFoundHint(msg string) error {
+	return &notFoundHint{msg: msg}
+}
+
 // withNotFoundHint wraps inner so ErrNotFound from Lookup carries an
 // actionable hint. The legacy file path is resolved up front (where ctx
 // is available) so Lookup can do its check without needing a context.

libs/auth/storage/not_found_hint_test.go

@@ -3,6 +3,7 @@ package storage
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"testing"
@@ -118,6 +119,36 @@ func TestNotFoundHintCache_StoreIsDelegated(t *testing.T) {
 	require.NoError(t, c.Store("k", &oauth2.Token{AccessToken: "abc"}))
 }
 
+func TestHintForNotFound(t *testing.T) {
+	t.Run("nil returns empty", func(t *testing.T) {
+		assert.Empty(t, HintForNotFound(nil))
+	})
+
+	t.Run("plain ErrNotFound returns empty", func(t *testing.T) {
+		// An unwrapped cache.ErrNotFound carries no hint, so the caller
+		// (e.g. `auth token`) falls back to its default error path.
+		assert.Empty(t, HintForNotFound(cache.ErrNotFound))
+	})
+
+	t.Run("unrelated error returns empty", func(t *testing.T) {
+		assert.Empty(t, HintForNotFound(errors.New("something else")))
+	})
+
+	t.Run("notFoundHint returns the hint message", func(t *testing.T) {
+		h := &notFoundHint{msg: "do the thing"}
+		assert.Equal(t, "do the thing", HintForNotFound(h))
+	})
+
+	t.Run("notFoundHint behind an fmt.Errorf wrap returns the hint", func(t *testing.T) {
+		// The SDK wraps every cache error with `cache: %w`, so the hint
+		// is one Unwrap away when it surfaces in callers. errors.As must
+		// still find it.
+		h := &notFoundHint{msg: "do the thing"}
+		wrapped := fmt.Errorf("cache: %w", h)
+		assert.Equal(t, "do the thing", HintForNotFound(wrapped))
+	})
+}
+
 func TestLegacyCacheHasTokens(t *testing.T) {
 	tmp := t.TempDir()