Function formatSSHError

apps/sim/app/api/tools/ssh/utils.ts:35–103

* Format SSH error with helpful troubleshooting context

(err: Error, config: { host: string; port: number })

 * Format SSH error with helpful troubleshooting context
 */
function formatSSHError(err: Error, config: { host: string; port: number }): Error {
  const errorMessage = err.message.toLowerCase()
  const host = config.host
  const port = config.port

  if (errorMessage.includes('econnrefused') || errorMessage.includes('connection refused')) {
    return new Error(
      `Connection refused to ${host}:${port}. ` +
        `Please verify: (1) SSH server is running on the target machine, ` +
        `(2) Port ${port} is correct (default SSH port is 22), ` +
        `(3) Firewall allows connections to port ${port}.`
    )
  }

  if (errorMessage.includes('econnreset') || errorMessage.includes('connection reset')) {
    return new Error(
      `Connection reset by ${host}:${port}. ` +
        `This usually means: (1) Wrong port number (SSH default is 22), ` +
        `(2) Server rejected the connection, ` +
        `(3) Network/firewall interrupted the connection. ` +
        `Verify your SSH server configuration and port number.`
    )
  }

  if (errorMessage.includes('etimedout') || errorMessage.includes('timeout')) {
    return new Error(
      `Connection timed out to ${host}:${port}. ` +
        `Please verify: (1) Host "${host}" is reachable, ` +
        `(2) No firewall is blocking the connection, ` +
        `(3) The SSH server is responding.`
    )
  }

  if (errorMessage.includes('enotfound') || errorMessage.includes('getaddrinfo')) {
    return new Error(
      `Could not resolve hostname "${host}". ` +
        `Please verify the hostname or IP address is correct.`
    )
  }

  if (errorMessage.includes('authentication') || errorMessage.includes('auth')) {
    return new Error(
      `Authentication failed for user on ${host}:${port}. ` +
        `Please verify: (1) Username is correct, ` +
        `(2) Password or private key is valid, ` +
        `(3) User has SSH access on the server.`
    )
  }

  if (
    errorMessage.includes('key') &&
    (errorMessage.includes('parse') || errorMessage.includes('invalid'))
  ) {
    return new Error(
      `Invalid private key format. ` +
        `Please ensure you're using a valid OpenSSH private key. ` +
        `The key should start with "-----BEGIN" and end with "-----END".`
    )