wavetermdev/waveterm · error

--conn parameter is required

Error message

--conn parameter is required

What it means

serverRun validates that the --conn flag (connServerConnName) was provided before starting the connection server. Without a connection name it cannot determine which remote to serve, so it returns this validation error (also written to the log file if one is open).

Source

Thrown at cmd/wsh/cmd/wshcmd-connserver.go:463

		logFilePath := fmt.Sprintf("/tmp/waveterm-connserver-%d.log", os.Getuid())
		logFile, err = os.OpenFile(logFilePath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
		if err != nil {
			fmt.Fprintf(os.Stderr, "failed to open log file: %v\n", err)
			log.SetFlags(log.LstdFlags | log.Lmicroseconds)
			log.SetPrefix(fmt.Sprintf("[PID:%d] ", os.Getpid()))
		} else {
			defer logFile.Close()
			logWriter := io.MultiWriter(os.Stderr, logFile)
			log.SetOutput(logWriter)
			log.SetFlags(log.LstdFlags | log.Lmicroseconds)
			log.SetPrefix(fmt.Sprintf("[PID:%d] ", os.Getpid()))
		}
	}
	if connServerConnName == "" {
		if logFile != nil {
			fmt.Fprintf(logFile, "--conn parameter is required\n")
		}
		return fmt.Errorf("--conn parameter is required")
	}
	installErr := wshutil.InstallRcFiles()
	if installErr != nil {
		if logFile != nil {
			fmt.Fprintf(logFile, "error installing rc files: %v\n", installErr)
		}
		log.Printf("error installing rc files: %v", installErr)
	}
	sigutil.InstallSIGUSR1Handler()
	if connServerRouter {
		err := serverRunRouter()
		if err != nil && logFile != nil {
			fmt.Fprintf(logFile, "serverRunRouter error: %v\n", err)
		}
		return err
	}
	if connServerRouterDomainSocket {
		jwtToken, err := askForJwtToken()

View on GitHub (pinned to a4447c1563)

Solutions

1. Add --conn <connection-name> matching the connection name in Wave's connections settings
2. Check your ~/.ssh/config RemoteCommand/ProxyCommand line includes the --conn flag
3. Verify no shell quoting strips the flag from the spawned command line

Example fix

// before
wsh connserver --jwt "$JWT"
// after
wsh connserver --conn myserver --jwt "$JWT"

if [ -z "$CONN_NAME" ]; then
  echo "usage: wsh connserver --conn <name> ..." >&2
  exit 2
fi
wsh connserver --conn "$CONN_NAME" --jwt "$JWT"

if err := serverRun(cmd, args); err != nil {
	if strings.Contains(err.Error(), "--conn parameter is required") {
		fmt.Fprintln(os.Stderr, "add --conn <connection-name> from Wave's connection settings")
	}
	return err
}

When it happens

Trigger: Running `wsh connserver` without --conn (and without a configuration default that fills connServerConnName), e.g. manually invoking the command for debugging.

Common situations: Hand-crafting an SSH RemoteCommand line and omitting --conn; quoting issues in an SSH config that drop the flag; copying an example command that left the placeholder out.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• cannot parse connection name: %w
• ai:model is required
• chatOpts.ClientId is required
• ai:endpoint is required
• badge oref must be a block or tab (got %q)

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