What causes "remote host '{}' port must be greater than zero" in jdx/mise?

Set the host's `port` to a valid port (1–65535), e.g. 22 for SSH

remote host '{}' port must be greater than zero

Error message

remote host '{}' port must be greater than zero

What it means

Thrown by `RemoteHostConfig::validate_with_source` when a remote backup/archive host entry has `port = 0`. A TCP port of zero is not a usable connection port, so mise rejects the configuration up front rather than failing later during SSH/rsync. The host name is included in the message to identify which entry is invalid.

Source

Thrown at src/system/remote.rs:326

    pub(crate) fn destination(&self) -> String {
        match &self.user {
            Some(user) => format!("{user}@{}", self.host),
            None => self.host.clone(),
        }
    }

    fn validate(&self) -> Result<()> {
        self.validate_with_source(true)
    }

    fn validate_with_source(&self, archive: bool) -> Result<()> {
        validate_ssh_atom("host", &self.host)?;
        if let Some(user) = &self.user {
            validate_ssh_atom("user", user)?;
        }
        if self.port == Some(0) {
            bail!("remote host '{}' port must be greater than zero", self.name);
        }
        if archive && !self.source.is_dir() {
            bail!(
                "remote host '{}' source is not a directory: {}",
                self.name,
                self.source.display()
            );
        }
        if archive && !self.copy_links {
            for link in &self.copy_link {
                validate_copy_link(&self.source, link).wrap_err_with(|| {
                    format!("remote host '{}' has invalid copy_link", self.name)
                })?;
            }
        }
        if let Some(identity) = &self.identity_file
            && !identity.is_file()
        {

View on GitHub (pinned to afd2eddd3a)

Solutions

Set the host's `port` to a valid port (1–65535), e.g. 22 for SSH
Remove the `port` field entirely to use SSH's default port
Check any template/env substitution that produced 0 for the port

Example fix

// before (mise.toml)
[[remote_backup.hosts]]
name = "prod"
host = "prod.example.com"
port = 0
// after
[[remote_backup.hosts]]
name = "prod"
host = "prod.example.com"
port = 22

Defensive patterns

Strategy: validation

Validate before calling

fn valid_port(host: &RemoteHostConfig) -> bool {
    host.port.map(|p| p > 0 && p <= 65535).unwrap_or(true)
}

Type guard

fn port_is_valid(p: Option<u16>) -> bool {
    matches!(p, None | Some(1..=65535))
}

Prevention

Omit the `port` field instead of using 0 for the default
Validate host entries (ports in 1–65535) when generating config from templates
Review port values after any templating/substitution change

When it happens

Trigger: Defining a remote host in mise.toml with `port = 0` (typically a placeholder or parse mistake) and then calling `validate` or `apply_overrides` — e.g. when running a remote backup or archive operation.

Common situations: Copy-pasted config where the port was left at 0; a templating expression that evaluated to 0; misunderstanding that 0 means 'default port' (it does not — omit the port field instead).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/f3b1c0b8e9694b90. Report an issue: GitHub.