fix(sagemaker): improve SSH configuration error handling for SageMakare remote connections (#8328)

## Problem
When attempting to connect to a SageMaker Space, if the user's SSH
config has syntax errors (even outside the sm_* section), users would
see a cryptic error message:

```ssh check against host failed: 255```

This error message:
Didn't explain what was wrong
Didn't indicate it was an SSH config issue
Didn't provide a way to fix the problem

## Solution
Enhanced the SSH configuration error handling to provide a better user experience:

Shows a clear message explaining the issue.
Displays the actual SSH error (including line numbers) 
Provides an "Open SSH Config" button to directly open the config file for editing


https://github.com/user-attachments/assets/ef4f5a0f-0525-4e4c-9e96-a2081997dd81



---

- Treat all work as PUBLIC. Private `feature/x` branches will not be squash-merged at release time.
- Your code changes must meet the guidelines in [CONTRIBUTING.md](https://github.com/aws/aws-toolkit-vscode/blob/master/CONTRIBUTING.md#guidelines).
- License: I confirm that my contribution is made under the terms of the Apache 2.0 license.

Author: bhavya2109sharma

packages/core/src/awsService/sagemaker/commands.ts

@@ -17,12 +17,11 @@ import { prepareDevEnvConnection, tryRemoteConnection } from './model'
 import { ExtContext } from '../../shared/extensions'
 import { SagemakerClient } from '../../shared/clients/sagemaker'
 import { AccessDeniedException } from '@amzn/sagemaker-client'
-import { ToolkitError } from '../../shared/errors'
+import { ToolkitError, isUserCancelledError } from '../../shared/errors'
 import { showConfirmationMessage } from '../../shared/utilities/messages'
 import { RemoteSessionError } from '../../shared/remoteSession'
 import {
     ConnectFromRemoteWorkspaceMessage,
-    InstanceTypeError,
     InstanceTypeInsufficientMemory,
     InstanceTypeInsufficientMemoryMessage,
     RemoteAccess,
@@ -241,19 +240,29 @@ export async function openRemoteConnect(
         return
     }
 
-    const spaceName = node.spaceApp.SpaceName!
-    await tryRefreshNode(node)
+    try {
+        const spaceName = node.spaceApp.SpaceName!
+        await tryRefreshNode(node)
 
-    const remoteAccess = node.spaceApp.SpaceSettingsSummary?.RemoteAccess
-    const nodeStatus = node.getStatus()
+        const remoteAccess = node.spaceApp.SpaceSettingsSummary?.RemoteAccess
+        const nodeStatus = node.getStatus()
 
-    // Route to appropriate handler based on space state
-    if (nodeStatus === SpaceStatus.RUNNING && remoteAccess !== RemoteAccess.ENABLED) {
-        return handleRunningSpaceWithDisabledAccess(node, ctx, spaceName, sageMakerClient)
-    } else if (nodeStatus === SpaceStatus.STOPPED) {
-        return handleStoppedSpace(node, ctx, spaceName, sageMakerClient)
-    } else if (nodeStatus === SpaceStatus.RUNNING) {
-        return handleRunningSpaceWithEnabledAccess(node, ctx, spaceName)
+        // Route to appropriate handler based on space state
+        if (nodeStatus === SpaceStatus.RUNNING && remoteAccess !== RemoteAccess.ENABLED) {
+            return await handleRunningSpaceWithDisabledAccess(node, ctx, spaceName, sageMakerClient)
+        } else if (nodeStatus === SpaceStatus.STOPPED) {
+            return await handleStoppedSpace(node, ctx, spaceName, sageMakerClient)
+        } else if (nodeStatus === SpaceStatus.RUNNING) {
+            return await handleRunningSpaceWithEnabledAccess(node, ctx, spaceName)
+        }
+    } catch (err: any) {
+        // Suppress errors that don't need additional error messages:
+        // - User cancellations (checked by isUserCancelledError)
+        // - SSH config errors (already shown via modal in prepareDevEnvConnection)
+        if (isUserCancelledError(err) || (err instanceof ToolkitError && err.code === 'SshConfigError')) {
+            return
+        }
+        throw err
     }
 }
 
@@ -377,8 +386,10 @@ async function handleRunningSpaceWithDisabledAccess(
                 )
                 await tryRemoteConnection(node, ctx, progress)
             } catch (err: any) {
-                // Handle user declining instance type upgrade
-                if (err.code === InstanceTypeError) {
+                // Suppress errors that don't need additional error messages:
+                // - User cancellations (checked by isUserCancelledError)
+                // - SSH config errors (already shown via modal in prepareDevEnvConnection)
+                if (isUserCancelledError(err) || (err instanceof ToolkitError && err.code === 'SshConfigError')) {
                     return
                 }
                 throw new ToolkitError(`Remote connection failed: ${err.message}`, {
@@ -424,8 +435,10 @@ async function handleStoppedSpace(
             }
         )
     } catch (err: any) {
-        // Handle user declining instance type upgrade
-        if (err.code === InstanceTypeError) {
+        // Suppress errors that don't need additional error messages:
+        // - User cancellations (checked by isUserCancelledError)
+        // - SSH config errors (already shown via modal in prepareDevEnvConnection)
+        if (isUserCancelledError(err) || (err instanceof ToolkitError && err.code === 'SshConfigError')) {
             return
         }
         throw new ToolkitError(`Remote connection failed: ${(err as Error).message}`, {

packages/core/src/awsService/sagemaker/constants.ts

@@ -7,6 +7,7 @@ export const ConnectFromRemoteWorkspaceMessage =
     'Unable to establish new remote connection. Your last active VS Code window is connected to a remote workspace. To open a new SageMaker Studio connection, select your local VS Code window and try again.'
 
 export const InstanceTypeError = 'InstanceTypeError'
+export const SshConfigError = 'SshConfigError'
 
 export const InstanceTypeMinimum = 'ml.t3.large'
 
@@ -46,6 +47,10 @@ export const InstanceTypeNotSelectedMessage = (spaceName: string) => {
 export const RemoteAccessRequiredMessage =
     'This space requires remote access to be enabled.\nWould you like to restart the space and connect?\nAny unsaved work will be lost.'
 
+export const SshConfigErrorMessage = () => {
+    return `Unable to connect. Your SSH config file contains errors. Fix the errors to continue.`
+}
+
 export const SmusDeeplinkSessionExpiredError = {
     title: 'Session Disconnected',
     message:

packages/core/src/awsService/sagemaker/model.ts

@@ -6,7 +6,7 @@
 // Disabled: detached server files cannot import vscode.
 /* eslint-disable no-restricted-imports */
 import * as vscode from 'vscode'
-import { sshAgentSocketVariable, startSshAgent, startVscodeRemote } from '../../shared/extensions/ssh'
+import { getSshConfigPath, sshAgentSocketVariable, startSshAgent, startVscodeRemote } from '../../shared/extensions/ssh'
 import { createBoundProcess, ensureDependencies } from '../../shared/remoteSession'
 import { SshConfig } from '../../shared/sshConfig'
 import { Result } from '../../shared/utilities/result'
@@ -23,6 +23,7 @@ import { ToolkitError } from '../../shared/errors'
 import { SagemakerSpaceNode } from './explorer/sagemakerSpaceNode'
 import { sleep } from '../../shared/utilities/timeoutUtils'
 import { SagemakerUnifiedStudioSpaceNode } from '../../sagemakerunifiedstudio/explorer/nodes/sageMakerUnifiedStudioSpaceNode'
+import { SshConfigError, SshConfigErrorMessage } from './constants'
 import globals from '../../shared/extensionGlobals'
 
 const logger = getLogger('sagemaker')
@@ -162,6 +163,28 @@ export async function prepareDevEnvConnection(
     const config = await sshConfig.ensureValid()
     if (config.isErr()) {
         const err = config.err()
+        logger.error(`sagemaker: failed to add ssh config section: ${err.message}`)
+
+        if (err instanceof ToolkitError && err.code === 'SshCheckFailed') {
+            const sshConfigPath = getSshConfigPath()
+            const openConfigButton = 'Open SSH Config'
+            const resp = await vscode.window.showErrorMessage(
+                SshConfigErrorMessage(),
+                { modal: true, detail: err.message },
+                openConfigButton
+            )
+
+            if (resp === openConfigButton) {
+                void vscode.window.showTextDocument(vscode.Uri.file(sshConfigPath))
+            }
+
+            // Throw error to stop the connection flow
+            // User is already notified via modal above, downstream handlers check the error code
+            throw new ToolkitError('Unable to connect: SSH configuration contains errors', {
+                code: SshConfigError,
+            })
+        }
+
         const logPrefix = connectionType === 'sm_hp' ? 'hyperpod' : 'sagemaker'
         logger.error(`${logPrefix}: failed to add ssh config section: ${err.message}`)
         throw err

packages/core/src/shared/sshConfig.ts

@@ -85,7 +85,20 @@ export class SshConfig {
     protected async matchSshSection() {
         const result = await this.checkSshOnHost()
         if (result.exitCode !== 0) {
-            return Result.err(result.error ?? new Error(`ssh check against host failed: ${result.exitCode}`))
+            // Format stderr error message for display to user
+            let errorMessage = result.stderr?.trim() || `ssh check against host failed: ${result.exitCode}`
+            const sshConfigPath = getSshConfigPath()
+            // Remove the SSH config file path prefix from error messages to make them more readable
+            // SSH errors often include the full path like "/Users/name/.ssh/config: line 5: Bad configuration option"
+            errorMessage = errorMessage.replace(new RegExp(`${sshConfigPath}:? `, 'g'), '').trim()
+
+            if (result.error) {
+                // System level error
+                return Result.err(ToolkitError.chain(result.error, errorMessage))
+            }
+
+            // SSH ran but returned error exit code
+            return Result.err(new ToolkitError(errorMessage, { code: 'SshCheckFailed' }))
         }
         const matches = result.stdout.match(this.proxyCommandRegExp)
         return Result.ok(matches?.[0])

packages/core/src/test/shared/sshConfig.test.ts

@@ -26,6 +26,7 @@ class MockSshConfig extends SshConfig {
     // State variables to track logic flow.
     public testIsWin: boolean = false
     public configSection: string = ''
+    public exitCodeOverride: number = 0
 
     public async getProxyCommandWrapper(command: string): Promise<Result<string, ToolkitError>> {
         return await this.getProxyCommand(command)
@@ -51,7 +52,7 @@ class MockSshConfig extends SshConfig {
 
     protected override async checkSshOnHost(): Promise<ChildProcessResult> {
         return {
-            exitCode: 0,
+            exitCode: this.exitCodeOverride,
             error: undefined,
             stdout: this.configSection,
             stderr: '',
@@ -95,6 +96,10 @@ describe('VscodeRemoteSshConfig', async function () {
     })
 
     describe('matchSshSection', async function () {
+        beforeEach(function () {
+            config.exitCodeOverride = 0
+        })
+
         it('returns ok with match when proxycommand is present', async function () {
             const testSection = `proxycommandfdsafdsafd${testProxyCommand}sa342432`
             const result = await config.testMatchSshSection(testSection)
@@ -110,6 +115,16 @@ describe('VscodeRemoteSshConfig', async function () {
             const match = result.unwrap()
             assert.strictEqual(match, undefined)
         })
+
+        it('returns error when ssh check fails with non-zero exit code', async function () {
+            config.exitCodeOverride = 255
+            const testSection = `some config`
+            const result = await config.testMatchSshSection(testSection)
+            assert.ok(result.isErr())
+            const error = result.err()
+            assert.ok(error.message.includes('ssh check against host failed'))
+            assert.ok(error.message.includes('255'))
+        })
     })
 
     describe('verifySSHHost', async function () {
@@ -122,6 +137,7 @@ describe('VscodeRemoteSshConfig', async function () {
         })
 
         beforeEach(function () {
+            config.exitCodeOverride = 0
             promptUserToConfigureSshConfigStub.resetHistory()
         })
 

packages/toolkit/.changes/next-release/Bug Fix-3550c6a1-d356-45cc-a404-c87e2d2ee393.json

@@ -0,0 +1,4 @@
+{
+	"type": "Bug Fix",
+	"description": "SageMaker: SSH configuration errors now display line numbers and include an \"Open SSH Config\" button"
+}