Billionmail/BillionMail · error

admin username length must be between 4-32

Error message

admin username length must be between 4-32

What it means

For the ADMIN_USERNAME key (case-insensitive), validateConfigValue enforces a length of 4-32 bytes. Values shorter than 4 or longer than 32 are rejected with this message before the username is persisted.

Source

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

func parseInt(s string, defaultValue int) int {
	if v, err := strconv.Atoi(s); err == nil {
		return v
	}
	return defaultValue
}

// validateConfigValue
func validateConfigValue(key, value string) error {
	// Basic length check
	if len(value) > 1024 {
		return fmt.Errorf("configuration value too long, maximum 1024 characters")
	}

	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":

View on GitHub (pinned to fc36c76c05)

Solutions

1. Choose a username of 4-32 characters
2. Trim whitespace and check len(value) before calling the API
3. Use letters, numbers and underscores only (next validator also applies)
4. If you need a longer login name, use the email field rather than ADMIN_USERNAME

Example fix

// before
setConfig("ADMIN_USERNAME", "ab") // rejected
// after
setConfig("ADMIN_USERNAME", "admin") // 4-32 chars

function isValidAdminUsername(u) {
  return typeof u === 'string' && u.length >= 4 && u.length <= 32;
}

function isAdminUsername(v: unknown): v is string {
  return typeof v === 'string' && v.length >= 4 && v.length <= 32;
}

When it happens

Trigger: SetSystemConfig/SetSystemConfigKey with key ADMIN_USERNAME/admin_username and a value of length <4 (e.g. 'ab') or >32 characters.

Common situations: Admin setups using very short usernames like 'adm'; machine-generated long usernames (email-like addresses) pasted as the admin username.

Related errors

• admin username can only contain letters, numbers and undersc
• password length must be at least 4 characters
• configuration value too long, maximum 1024 characters
• required column 'email' not found
• You cannot create more than 5000 batches

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