Billionmail/BillionMail · error

hostname format is incorrect

Error message

hostname format is incorrect

What it means

validateConfigValue in the settings controller rejects a value for the BILLIONMAIL_HOSTNAME config key when public.IsValidHostname fails. Hostnames are written to mail infrastructure config (Postfix/Dovecot) and must contain only letters, numbers, dots and hyphens; anything else would break downstream service configuration. The error is returned from SetSystemConfig/SetSystemConfigKey before the value is persisted.

Source

Thrown at core/internal/controller/settings/settings.go:208

	switch key {
	case "ADMIN_USERNAME", "admin_username":
		// Admin username: allowed letters, numbers, underscores, length 4-32
		if len(value) < 4 || len(value) > 32 {
			return fmt.Errorf("admin username length must be between 4-32")
		}
		if !public.IsValidUsername(value) {
			return fmt.Errorf("admin username can only contain letters, numbers and underscores")
		}

	case "ADMIN_PASSWORD", "admin_password":
		if len(value) < 4 {
			return fmt.Errorf("password length must be at least 4 characters")
		}

	case "BILLIONMAIL_HOSTNAME", "billionmail_hostname":
		// Hostname: allowed letters, numbers, dots, hyphens
		if !public.IsValidHostname(value) {
			return fmt.Errorf("hostname format is incorrect")
		}

	case "SMTP_PORT", "SMTPS_PORT", "SUBMISSION_PORT", "IMAP_PORT", "IMAPS_PORT", "POP_PORT", "POPS_PORT", "HTTP_PORT", "HTTPS_PORT", "REDIS_PORT",
		"smtp", "smtps", "submission", "imap", "imaps", "pop", "pops", "http", "https", "redis_port":
		// Port: 1-65535
		port := public.ParseInt(value)
		if port < 1 || port > 65535 {
			return fmt.Errorf("port must be between 1-65535")
		}

	case "IPV4_NETWORK", "ipv4_network":
		// IPv4 network: CIDR format
		if !public.IsValidCIDR(value) {
			return fmt.Errorf("IPv4 network format is incorrect, please use CIDR format (e.g. 192.168.1.0/24)")
		}

	case "TZ", "timezone":
		// Timezone: check if it is a valid timezone

View on GitHub (pinned to fc36c76c05)

Solutions

1. Use a bare FQDN hostname containing only letters, numbers, dots and hyphens, e.g. mail.example.com
2. Strip scheme and port: 'https://mail.example.com:25' → 'mail.example.com'
3. Replace underscores with hyphens if the machine name contains them
4. Verify with the same regex the validator uses before calling the API

Example fix

// before
key: BILLIONMAIL_HOSTNAME, value: https://mail.example.com
// after
key: BILLIONMAIL_HOSTNAME, value: mail.example.com

const hostRe = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)*$/;
if (!hostRe.test(hostname)) throw new Error('hostname format is incorrect');

function isValidHostname(v: string): boolean {
  return /^[A-Za-z0-9.-]+$/.test(v) && !v.includes('..') && v.length <= 253;
}

try {
  await api.setSystemConfigKey('BILLIONMAIL_HOSTNAME', hostname);
} catch (e) {
  if (String(e.message).includes('hostname format')) {
    notify('Hostname may only contain letters, numbers, dots and hyphens');
  } else throw e;
}

When it happens

Trigger: Calling SetSystemConfig or SetSystemConfigKey with BILLIONMAIL_HOSTNAME (or billionmail_hostname) set to a value containing underscores, spaces, slashes, protocol prefixes (http://), trailing dots, or other characters outside [A-Za-z0-9.-].

Common situations: Admins paste a URL like 'https://mail.example.com' instead of the bare hostname, or use underscore names like 'mail_server' (valid in some DNS setups but rejected here), or include a port ('mail.example.com:25').

Related errors

• port must be between 1-65535
• IPv4 network format is incorrect, please use CIDR format (e.
• invalid timezone
• fail2ban value can only be y/n or 1/0
• retention_days must be a number

AI-assisted analysis of Billionmail/BillionMail@fc36c76c05 (2026-09-05). Data as JSON: /api/errors/f92e02cdb88b61f6. Report an issue: GitHub.