Billionmail/BillionMail · error

admin username can only contain letters, numbers and undersc

Error message

admin username can only contain letters, numbers and underscores

What it means

After the length check, ADMIN_USERNAME values must pass public.IsValidUsername, which permits only letters, numbers and underscores. Any other character (spaces, hyphens, dots, email '@', unicode) triggers this error.

Source

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

	}
	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":
		// Port: 1-65535
		port := public.ParseInt(value)
		if port < 1 || port > 65535 {

View on GitHub (pinned to fc36c76c05)

Solutions

1. Replace invalid characters with underscores, e.g. 'john.doe' -> 'john_doe'
2. Use only letters, numbers and underscores in the username
3. Trim leading/trailing whitespace and strip invisible characters before submitting
4. Store the email address in a separate email config/account field

Example fix

// before
setConfig("ADMIN_USERNAME", "john.doe@example.com")
// after
setConfig("ADMIN_USERNAME", "john_doe")

function isValidUsernameChars(u) {
  return typeof u === 'string' && /^[A-Za-z0-9_]{4,32}$/.test(u);
}

function isPlainUsername(v: unknown): v is string {
  return typeof v === 'string' && /^[A-Za-z0-9_]{4,32}$/.test(v);
}

When it happens

Trigger: SetSystemConfig with ADMIN_USERNAME containing characters outside [A-Za-z0-9_], e.g. 'john.doe', 'admin user', 'ops-admin', or 'user@example.com'.

Common situations: Using an email address as the admin username; names with spaces or dots; copy-paste including invisible whitespace or unicode characters.

Related errors

• admin username length must be between 4-32
• 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/61f21f980650232d. Report an issue: GitHub.