Improve error message when no subscriptions are found

cli/azd/pkg/errorhandler/pipeline_test.go

@@ -572,6 +572,17 @@ func TestPipeline_RBACErrors(t *testing.T) {
 	}
 }
 
+func TestPipeline_NoSubscriptionsFound(t *testing.T) {
+	pipeline := NewErrorHandlerPipeline(nil)
+
+	err := errors.New("no subscriptions found")
+	result := pipeline.Process(context.Background(), err)
+	require.NotNil(t, result, "Should match 'no subscriptions found' pattern")
+	assert.Equal(t, "No Azure subscriptions were found for your account.", result.Message)
+	assert.Contains(t, result.Suggestion, "azd auth login --tenant-id")
+	assert.NotEmpty(t, result.Links, "Should include documentation links")
+}
+
 func TestErrorSuggestionsYaml_IsValid(t *testing.T) {
 	// Verify the embedded YAML can be parsed
 	var config ErrorSuggestionsConfig

cli/azd/pkg/prompt/prompter.go

@@ -75,6 +75,8 @@ func (p *DefaultPrompter) PromptSubscription(ctx context.Context, msg string) (s
 	}
 
 	if len(subscriptionOptions) == 0 {
+		// NOTE: Error text must contain "no subscriptions found" to match the
+		// pattern in error_suggestions.yaml. Update both if rewording.
 		return "", errors.New(heredoc.Docf(
 			`no subscriptions found.
 			Ensure you have a subscription by visiting %s and search for Subscriptions in the search bar.

cli/azd/resources/error_suggestions.yaml

@@ -382,6 +382,24 @@ rules:
     message: "The Azure authentication session may have expired."
     suggestion: "Run 'azd auth login' to refresh your credentials, then retry."
 
+  # ============================================================================
+  # Subscription Errors
+  # ============================================================================
+
+  - patterns:
+      - "no subscriptions found"
+      - "no subscription found"
+    message: "No Azure subscriptions were found for your account."
+    suggestion: >
+      Ensure you have an active subscription at https://portal.azure.com.
+      If you have multiple tenants, run 'azd auth login --tenant-id <tenant-id>'
+      to sign in to a specific tenant. Multi-factor authentication (MFA) may prevent
+      automatic access to all tenants — visit the Azure portal and switch to each tenant
+      to refresh your MFA sessions, then retry 'azd auth login'.
+    links:
+      - url: "https://learn.microsoft.com/azure/developer/azure-developer-cli/reference#azd-auth-login"
+        title: "azd auth login reference"
+
   # ============================================================================
   # Text Pattern Rules — Specific patterns first
   # These are fallbacks for errors without typed Go structs.