firewall rule name '{name}' must contain only ASCII letters,

Error message

firewall rule name '{name}' must contain only ASCII letters, numbers, '-' or '_'

What it means

Thrown by validate_name (src/system/firewall.rs) when building a Linux firewall request from [bootstrap.linux.firewall] config. Rule names become stable identifiers for the generated iptables/nftables rules, so they must be 1-64 bytes of ASCII letters, digits, '-' or '_' only. Empty names, names over 64 bytes, or any other byte (space, dot, slash, UTF-8) fail fast at config parse time instead of producing unusable firewall rules.

Source

Thrown at src/system/firewall.rs:1963

fn command_error(program: &str, args: &[&str], output: &Output) -> eyre::Report {
    eyre!(
        "{} failed with {}: {}",
        shell_words::join(
            std::iter::once(program.to_string()).chain(args.iter().map(|arg| (*arg).to_string()))
        ),
        output.status,
        String::from_utf8_lossy(&output.stderr).trim()
    )
}

fn validate_name(name: &str) -> Result<()> {
    if name.is_empty()
        || name.len() > 64
        || !name
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
    {
        bail!("firewall rule name '{name}' must contain only ASCII letters, numbers, '-' or '_'");
    }
    Ok(())
}

fn validate_interface(interface: &str) -> Result<String> {
    if interface.is_empty()
        || interface.len() > 15
        || !interface
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b':'))
    {
        bail!("firewall interface '{interface}' is invalid");
    }
    Ok(interface.to_string())
}

fn parse_ssh_connection(value: &str) -> Result<SshConnection> {
    let fields = value.split_ascii_whitespace().collect::<Vec<_>>();

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Rename the rule to contain only ASCII letters, digits, '-' and '_' (e.g. allow_ssh_22)
Shorten the name to 64 bytes or fewer
Re-run mise bootstrap (or the firewall plan step) to confirm the config parses

Example fix

# before (mise.toml)
# rule name contains spaces/parens -> rejected
"allow ssh (22)" = { port = 22 }

# after
allow_ssh_22 = { port = 22 }

Defensive patterns

Strategy: validation

Validate before calling

# before running mise bootstrap, check every rule name
mise config ls 2>/dev/null; grep -oE '"?[^"=]+"?\s*=' mise.toml | tr -d ' "=' | while read -r n; do
  echo "$n" | grep -qE '^[A-Za-z0-9_-]{1,64}$' || echo "invalid firewall rule name: $n"
done

Prevention

Use a naming convention of only lowercase letters, digits and hyphens for firewall rule names
Lint mise.toml in CI with a regex check for rule keys: ^[A-Za-z0-9_-]{1,64}$
Never paste free-text descriptions into rule name keys

When it happens

Trigger: Declaring a firewall rule whose name contains a character outside [A-Za-z0-9_-] — e.g. a key like "allow ssh (22)", "web/http", "règle-1" — or a name longer than 64 bytes, or an empty name. Fires while parsing [bootstrap.linux.firewall] during mise bootstrap.

Common situations: Copying rule names from pf/ufw/firewalld configs that permit spaces, dots, or slashes; using FQDNs or free-text descriptions as rule names; localized non-ASCII names; long descriptive names generated by templating.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/4de44c90bc3b55db. Report an issue: GitHub.