Show logs command hint on app deployment failure (#4133)

## Changes
- Show logs command hint on app deployment failure
- Describe view app logs in MCP guidance

## Why
Improve `apps logs` command discoverability.

## Screenshot

<img width="1288" height="729" alt="Screenshot 2025-12-11 at 22 57 11"
src="https://github.com/user-attachments/assets/7ac2317e-1532-4d44-9e5f-029eac69e169"
/>

## Tests
Unit tests

Author: pkosiec

cmd/workspace/apps/errors.go

@@ -0,0 +1,75 @@
+package apps
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/databricks/databricks-sdk-go/apierr"
+	"github.com/databricks/databricks-sdk-go/retries"
+	"github.com/spf13/cobra"
+)
+
+const tailLinesSuggestedValue = 100
+
+// isDeploymentWaitError checks if the error is from the deployment wait phase.
+// These are errors wrapped by retries.Halt() during GetWithTimeout().
+// Excludes API client errors (4xx) which are validation errors before deployment starts.
+func isDeploymentWaitError(err error) bool {
+	var retriesErr *retries.Err
+	if !errors.As(err, &retriesErr) || !retriesErr.Halt {
+		return false
+	}
+
+	// Exclude API client errors (4xx) (e.g. app not found)
+	var apiErr *apierr.APIError
+	if errors.As(err, &apiErr) && apiErr.StatusCode >= 400 && apiErr.StatusCode < 500 {
+		return false
+	}
+
+	return true
+}
+
+// wrapDeploymentError wraps the error with logs hint if it's a deployment wait error.
+// Returns the original error unchanged if it's not a deployment wait error.
+func wrapDeploymentError(cmd *cobra.Command, appName string, err error) error {
+	if err != nil && isDeploymentWaitError(err) {
+		return newAppDeploymentError(cmd, appName, err)
+	}
+	return err
+}
+
+// AppDeploymentError wraps deployment errors with a helpful logs command suggestion.
+type AppDeploymentError struct {
+	Underlying error
+	appName    string
+	profile    string
+}
+
+func (e *AppDeploymentError) Error() string {
+	suggestion := fmt.Sprintf("\n\nTo view app logs, run:\n  databricks apps logs %s --tail-lines %d",
+		e.appName,
+		tailLinesSuggestedValue,
+	)
+	if e.profile != "" {
+		suggestion = fmt.Sprintf("%s --profile %s", suggestion, e.profile)
+	}
+	return e.Underlying.Error() + suggestion
+}
+
+func (e *AppDeploymentError) Unwrap() error {
+	return e.Underlying
+}
+
+// newAppDeploymentError creates an AppDeploymentError with profile info from the command.
+func newAppDeploymentError(cmd *cobra.Command, appName string, err error) error {
+	profile := ""
+	profileFlag := cmd.Flag("profile")
+	if profileFlag != nil && profileFlag.Value.String() != "" {
+		profile = profileFlag.Value.String()
+	}
+	return &AppDeploymentError{
+		Underlying: err,
+		appName:    appName,
+		profile:    profile,
+	}
+}

cmd/workspace/apps/errors_test.go

@@ -0,0 +1,168 @@
+package apps
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/databricks/databricks-sdk-go/apierr"
+	"github.com/databricks/databricks-sdk-go/retries"
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAppDeploymentError_Error_WithoutProfile(t *testing.T) {
+	originalErr := errors.New("deployment failed: timeout")
+	appErr := &AppDeploymentError{
+		Underlying: originalErr,
+		appName:    "my-app",
+		profile:    "",
+	}
+
+	result := appErr.Error()
+
+	assert.Contains(t, result, "deployment failed: timeout")
+	assert.Contains(t, result, "To view app logs, run:")
+	assert.Contains(t, result, "databricks apps logs my-app --tail-lines 100")
+	assert.NotContains(t, result, "--profile")
+}
+
+func TestAppDeploymentError_Error_WithProfile(t *testing.T) {
+	originalErr := errors.New("deployment failed: timeout")
+	appErr := &AppDeploymentError{
+		Underlying: originalErr,
+		appName:    "my-app",
+		profile:    "production",
+	}
+
+	result := appErr.Error()
+
+	assert.Contains(t, result, "deployment failed: timeout")
+	assert.Contains(t, result, "To view app logs, run:")
+	assert.Contains(t, result, "databricks apps logs my-app --tail-lines 100 --profile production")
+}
+
+func TestAppDeploymentError_Unwrap(t *testing.T) {
+	originalErr := errors.New("original error")
+	appErr := &AppDeploymentError{
+		Underlying: originalErr,
+		appName:    "my-app",
+		profile:    "",
+	}
+
+	unwrapped := appErr.Unwrap()
+
+	require.Equal(t, originalErr, unwrapped)
+	assert.ErrorIs(t, appErr, originalErr, "errors.Is should work with wrapped error")
+}
+
+func TestWrapDeploymentError(t *testing.T) {
+	tests := []struct {
+		name          string
+		err           error
+		appName       string
+		expectWrapped bool
+		description   string
+	}{
+		{
+			name:          "nil error",
+			err:           nil,
+			appName:       "test-app",
+			expectWrapped: false,
+			description:   "nil error should return nil unchanged",
+		},
+		{
+			name:          "plain error without retries wrapper",
+			err:           errors.New("some error"),
+			appName:       "test-app",
+			expectWrapped: false,
+			description:   "plain errors should not be wrapped",
+		},
+		{
+			name:          "retries.Err with Halt=false",
+			err:           retries.Continues("still in progress"),
+			appName:       "test-app",
+			expectWrapped: false,
+			description:   "transient retries errors should not be wrapped",
+		},
+		{
+			name: "retries.Err with 404 API error (not found)",
+			err: retries.Halt(fmt.Errorf("API error: %w", &apierr.APIError{
+				StatusCode: 404,
+				ErrorCode:  "NOT_FOUND",
+				Message:    "App with name test-app does not exist or is deleted.",
+			})),
+			appName:       "test-app",
+			expectWrapped: false,
+			description:   "404 not found errors should not be wrapped with logs hint",
+		},
+		{
+			name: "retries.Err with 400 API error (bad request)",
+			err: retries.Halt(fmt.Errorf("API error: %w", &apierr.APIError{
+				StatusCode: 400,
+				ErrorCode:  "BAD_REQUEST",
+				Message:    "Invalid request parameters",
+			})),
+			appName:       "test-app",
+			expectWrapped: false,
+			description:   "400 bad request errors should not be wrapped with logs hint",
+		},
+		{
+			name: "retries.Err with 403 API error (forbidden)",
+			err: retries.Halt(fmt.Errorf("API error: %w", &apierr.APIError{
+				StatusCode: 403,
+				ErrorCode:  "FORBIDDEN",
+				Message:    "Access denied",
+			})),
+			appName:       "test-app",
+			expectWrapped: false,
+			description:   "403 forbidden errors should not be wrapped with logs hint",
+		},
+		{
+			name: "retries.Err with 500 API error (server error)",
+			err: retries.Halt(fmt.Errorf("API error: %w", &apierr.APIError{
+				StatusCode: 500,
+				ErrorCode:  "INTERNAL_ERROR",
+				Message:    "Internal server error",
+			})),
+			appName:       "test-app",
+			expectWrapped: true,
+			description:   "500 server errors during wait should be wrapped with logs hint",
+		},
+		{
+			name:          "retries.Err without API error (deployment failure)",
+			err:           retries.Halt(errors.New("failed to reach SUCCEEDED, got FAILED: Error building app")),
+			appName:       "test-app",
+			expectWrapped: true,
+			description:   "deployment failures should be wrapped with logs hint",
+		},
+		{
+			name:          "retries.Err without API error (timeout)",
+			err:           retries.Halt(errors.New("timeout waiting for deployment")),
+			appName:       "test-app",
+			expectWrapped: true,
+			description:   "timeout errors should be wrapped with logs hint",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{}
+			result := wrapDeploymentError(cmd, tt.appName, tt.err)
+
+			if tt.expectWrapped {
+				var appErr *AppDeploymentError
+				require.ErrorAs(t, result, &appErr, tt.description)
+				assert.Equal(t, tt.appName, appErr.appName)
+				assert.ErrorIs(t, result, tt.err, "wrapped error should unwrap to original")
+				assert.Contains(t, result.Error(), "To view app logs, run:", "should contain logs hint")
+			} else {
+				assert.Equal(t, tt.err, result, tt.description)
+				if tt.err != nil {
+					assert.NotContains(t, result.Error(), "To view app logs", "should not contain logs hint")
+				}
+			}
+		})
+	}
+}

cmd/workspace/apps/overrides.go

@@ -22,10 +22,46 @@ func listDeploymentsOverride(listDeploymentsCmd *cobra.Command, listDeploymentsR
 	{{end}}`)
 }
 
+func createOverride(createCmd *cobra.Command, createReq *apps.CreateAppRequest) {
+	originalRunE := createCmd.RunE
+	createCmd.RunE = func(cmd *cobra.Command, args []string) error {
+		err := originalRunE(cmd, args)
+		return wrapDeploymentError(cmd, createReq.App.Name, err)
+	}
+}
+
+func deployOverride(deployCmd *cobra.Command, deployReq *apps.CreateAppDeploymentRequest) {
+	originalRunE := deployCmd.RunE
+	deployCmd.RunE = func(cmd *cobra.Command, args []string) error {
+		err := originalRunE(cmd, args)
+		return wrapDeploymentError(cmd, deployReq.AppName, err)
+	}
+}
+
+func createUpdateOverride(createUpdateCmd *cobra.Command, createUpdateReq *apps.AsyncUpdateAppRequest) {
+	originalRunE := createUpdateCmd.RunE
+	createUpdateCmd.RunE = func(cmd *cobra.Command, args []string) error {
+		err := originalRunE(cmd, args)
+		return wrapDeploymentError(cmd, createUpdateReq.AppName, err)
+	}
+}
+
+func startOverride(startCmd *cobra.Command, startReq *apps.StartAppRequest) {
+	originalRunE := startCmd.RunE
+	startCmd.RunE = func(cmd *cobra.Command, args []string) error {
+		err := originalRunE(cmd, args)
+		return wrapDeploymentError(cmd, startReq.Name, err)
+	}
+}
+
 func init() {
 	cmdOverrides = append(cmdOverrides, func(cmd *cobra.Command) {
 		cmd.AddCommand(newLogsCommand())
 	})
 	listOverrides = append(listOverrides, listOverride)
 	listDeploymentsOverrides = append(listDeploymentsOverrides, listDeploymentsOverride)
+	createOverrides = append(createOverrides, createOverride)
+	deployOverrides = append(deployOverrides, deployOverride)
+	createUpdateOverrides = append(createUpdateOverrides, createUpdateOverride)
+	startOverrides = append(startOverrides, startOverride)
 }

experimental/apps-mcp/lib/prompts/target_apps.tmpl

@@ -20,6 +20,10 @@ This is battle-tested to catch common issues before deployment. Prefer using thi
 ### View and Manage
   invoke_databricks_cli 'bundle summary'
 
+### View App Logs
+To troubleshoot deployed apps, view their logs:
+  invoke_databricks_cli 'apps logs <app-name> --tail-lines 100'
+
 ### Local Development vs Deployed Apps
 
 During development: