wavetermdev/waveterm · error

invalid ssh remote name (%s): %w

Error message

invalid ssh remote name (%s): %w

What it means

startNewJob validates the block's connection name via remote.ParseOpts before dialing. This error means the configured conn name is not a valid/known SSH remote identity (bad format or unresolvable remote config). The block cannot determine SSH options for the connection.

Source

Thrown at pkg/blockcontroller/durableshellcontroller.go:239

	if len(inputUnion.InputData) > 0 {
		data.InputData64 = base64.StdEncoding.EncodeToString(inputUnion.InputData)
	}
	return jobcontroller.SendInput(context.Background(), data)
}

func (dsc *DurableShellController) startNewJob(ctx context.Context, blockMeta waveobj.MetaMapType, connName string, rtOpts *waveobj.RuntimeOpts) (string, error) {
	termSize := waveobj.TermSize{
		Rows: shellutil.DefaultTermRows,
		Cols: shellutil.DefaultTermCols,
	}
	if rtOpts != nil && rtOpts.TermSize.Rows > 0 && rtOpts.TermSize.Cols > 0 {
		termSize = rtOpts.TermSize
	}
	cmdStr := blockMeta.GetString(waveobj.MetaKey_Cmd, "")
	cwd := blockMeta.GetString(waveobj.MetaKey_CmdCwd, "")
	opts, err := remote.ParseOpts(connName)
	if err != nil {
		return "", fmt.Errorf("invalid ssh remote name (%s): %w", connName, err)
	}
	conn := conncontroller.MaybeGetConn(opts)
	if conn == nil {
		return "", fmt.Errorf("connection %q not found", connName)
	}
	connRoute := wshutil.MakeConnectionRouteId(connName)
	remoteInfo, err := wshclient.RemoteGetInfoCommand(wshclient.GetBareRpcClient(), &wshrpc.RpcOpts{Route: connRoute, Timeout: 2000})
	if err != nil {
		return "", fmt.Errorf("unable to obtain remote info from connserver: %w", err)
	}
	shellType := shellutil.GetShellTypeFromShellPath(remoteInfo.Shell)
	swapToken := makeSwapToken(ctx, ctx, dsc.BlockId, blockMeta, connName, shellType)
	sockName := wavebase.GetPersistentRemoteSockName(wstore.GetClientId())
	rpcContext := wshrpc.RpcContext{
		ProcRoute: true,
		SockName:  sockName,
		BlockId:   dsc.BlockId,
		Conn:      connName,

View on GitHub (pinned to a4447c1563)

Solutions

1. Verify the block's meta:conn value matches an existing remote profile name.
2. Re-add the remote in connection settings, then retry Start.
3. Update the block meta to the correct connection name.
4. For local/wsl shells, ensure the correct conn type is used instead of an SSH name.

Example fix

// before
meta := waveobj.MetaMapType{"conn": "prod-servr"} // typo, ParseOpts fails
// after
meta := waveobj.MetaMapType{"conn": "prod-server"} // matches a configured remote

opts, err := remote.ParseOpts(connName)
if err != nil {
    return fmt.Errorf("conn %q is not a valid ssh remote: %w", connName, err)
}

if err := controller.Start(ctx, meta, rtOpts, false); err != nil {
    if strings.Contains(err.Error(), "invalid ssh remote name") {
        // prompt user to fix meta:conn in block settings
    }
    return err
}

When it happens

Trigger: Block meta has meta:conn set to a name that fails remote.ParseOpts — misspelled remote name, removed remote profile, or a conn name belonging to a non-SSH scheme where SSH opts parsing is invalid.

Common situations: User renamed or deleted an SSH remote profile in settings but old blocks still reference it; typo in conn name; connecting to a wsl:// conn through a code path expecting SSH opts.

Related errors

• Invalid CSS color: ${color}
• cannot parse connection name: %w
• --conn parameter is required
• failed to reconnect to job: %w
• connection %q not found

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