slackhq/nebula · error

sshd.listen must be provided

Error message

sshd.listen must be provided

What it means

configSSH reads the "sshd.listen" config key and requires a non-empty host:port value before it can configure the SSH server. If the key is missing or set to an empty string, configuration aborts with this error. It is a startup-time configuration validation, so the process cannot begin serving SSH without a listen address.

Source

Thrown at ssh.go:84

				ssh.Stop()
			}
			if sshRun != nil {
				go sshRun()
			}
		} else {
			ssh.Stop()
		}
	})
}

// configSSH reads the ssh info out of the passed-in Config and
// updates the passed-in SSHServer. On success, it returns a function
// that callers may invoke to run the configured ssh server. On
// failure, it returns nil, error.
func configSSH(l *slog.Logger, ssh *sshd.SSHServer, c *config.C) (func(), error) {
	listen := c.GetString("sshd.listen", "")
	if listen == "" {
		return nil, fmt.Errorf("sshd.listen must be provided")
	}

	_, port, err := net.SplitHostPort(listen)
	if err != nil {
		return nil, fmt.Errorf("invalid sshd.listen address: %s", err)
	}
	if port == "22" {
		return nil, fmt.Errorf("sshd.listen can not use port 22")
	}

	hostKeyPathOrKey := c.GetString("sshd.host_key", "")
	if hostKeyPathOrKey == "" {
		return nil, fmt.Errorf("sshd.host_key must be provided")
	}

	var hostKeyBytes []byte
	if strings.Contains(hostKeyPathOrKey, "-----BEGIN") {
		hostKeyBytes = []byte(hostKeyPathOrKey)

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Set sshd.listen in your config, e.g. sshd.listen = "0.0.0.0:2222".
2. Set the corresponding environment variable if config comes from env.
3. Check the config file is actually being loaded (correct path/flag) so the key is present.

Example fix

// before (config)
[sshd]
# listen missing
// after (config)
[sshd]
listen = "0.0.0.0:2222"

if cfg.GetString("sshd.listen", "") == "" {
    return errors.New("sshd.listen is required: set it to e.g. 0.0.0.0:2222")
}

run, err := configSSH(logger, srv, c)
if err != nil {
    if strings.Contains(err.Error(), "sshd.listen must be provided") {
        logger.Error("missing required config key", "key", "sshd.listen")
        os.Exit(78) // EX_CONFIG
    }
    return err
}

When it happens

Trigger: Running the binary with no sshd.listen in the config file / environment (c.GetString("sshd.listen", "") returns ""), or explicitly setting sshd.listen="" in ssh.go's configSSH.

Common situations: Fresh deployments where the example config was not copied; renaming the key in a config migration; env var not exported so the default empty string is used; YAML indentation putting sshd.listen under the wrong block.

Related errors

• sshd.host_key must be provided
• invalid sshd.listen address: %s
• sshd.listen can not use port 22
• error while loading sshd.host_key file: %s
• error while adding sshd.host_key: %s

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/029fc9cf88133927. Report an issue: GitHub.