What causes "ssh client is not connected" in wavetermdev/waveterm?

Wait until the connection reaches Status_Connected before calling GetEnvironmentMaps

ssh client is not connected

Error message

ssh client is not connected

What it means

GetEnvironmentMaps is a testing/diagnostic helper that captures the remote environment both with and without a PTY. It first requires an active *ssh.Client; if GetClient() returns nil (connection not established or already torn down), it fails immediately with 'ssh client is not connected'.

Source

Thrown at pkg/remote/conncontroller/conncontroller.go:336

		return false, "not-installed", strings.TrimSpace(strings.TrimPrefix(wshVersionLine, "not-installed")), nil
	}
	parts := strings.Fields(wshVersionLine)
	if len(parts) != 2 {
		return false, "", "", fmt.Errorf("unexpected version format: %s", wshVersionLine)
	}
	clientVersion := parts[1]
	expectedVersion := fmt.Sprintf("v%s", wavebase.WaveVersion)
	if semver.Compare(clientVersion, expectedVersion) < 0 {
		return false, clientVersion, "", nil
	}
	return true, clientVersion, "", nil
}

// for testing only -- trying to determine the env difference when attaching or not attaching a pty to an ssh session
func (conn *SSHConn) GetEnvironmentMaps(ctx context.Context) (map[string]string, map[string]string, error) {
	client := conn.GetClient()
	if client == nil {
		return nil, nil, fmt.Errorf("ssh client is not connected")
	}

	noPtyEnv, err := conn.getEnvironmentNoPty(ctx, client)
	if err != nil {
		return nil, nil, fmt.Errorf("error getting environment without PTY: %w", err)
	}

	ptyEnv, err := conn.getEnvironmentWithPty(ctx, client)
	if err != nil {
		return nil, nil, fmt.Errorf("error getting environment with PTY: %w", err)
	}

	return noPtyEnv, ptyEnv, nil
}

func runSessionWithContext(ctx context.Context, session *ssh.Session, cmd string) error {
	errCh := make(chan error, 1)

View on GitHub (pinned to a4447c1563)

Solutions

Wait until the connection reaches Status_Connected before calling GetEnvironmentMaps
Reconnect the connection and retry once the client is available
Check connection logs for authentication or network failures that prevented client creation

Example fix

// before
conn.GetEnvironmentMaps(ctx) // client may be nil
// after
if conn.GetStatus() != remote.Status_Connected || conn.GetClient() == nil {
    return fmt.Errorf("cannot get env: connection not established")
}
noPty, pty, err := conn.GetEnvironmentMaps(ctx)

Defensive patterns

Strategy: validation

Validate before calling

if conn.GetClient() == nil {
    return fmt.Errorf("connection not established")
}

Try / catch

_, _, err := conn.GetEnvironmentMaps(ctx)
if err != nil && strings.Contains(err.Error(), "ssh client is not connected") {
    // wait for connect or trigger reconnect, then retry
}

Prevention

Only run diagnostics on connections in Status_Connected
Await connection-ready events before issuing client-dependent calls
Handle disconnects by invalidating in-flight diagnostics

When it happens

Trigger: Calling GetEnvironmentMaps before the SSH connection finished connecting, or after it was disconnected/cleaned up so conn.GetClient() is nil.

Common situations: Diagnostics invoked on a connection in Disconnected or Connecting state; SSH auth failed so no client was created; connection closed while diagnostics were requested.

Related errors

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/96ab1b6a2d35184b. Report an issue: GitHub.