homebridge/homebridge · critical

Not a valid username: ${username}. Must be 6 pairs of colon-

Error message

Not a valid username: ${username}. Must be 6 pairs of colon-separated hexadecimal chars (A-F 0-9), like a MAC address.

What it means

Homebridge requires the main bridge's `username` in config.json to be a MAC-address-style identifier: exactly 6 pairs of colon-separated hexadecimal characters (A-F, 0-9). It is used as the HAP bridge's unique device ID. loadConfig uppercases the value if it is a string and then validates it with validMacAddress(); any non-conforming value aborts startup with this TypeError-style Error.

Source

Thrown at src/server.ts:415

    bridge.pin = bridge.pin || defaultBridge.pin
    config.bridge = bridge

    // Validate Matter port pool configuration. Must run after bridge defaults
    // are filled in, since the cast to HomebridgeConfig only becomes honest at
    // that point.
    MatterConfigCollector.validateMatterPortsPool(config as HomebridgeConfig)

    // Normalise the main bridge username to uppercase so downstream comparisons
    // (validMacAddress, registry lookups, child-bridge dedup) stay case-consistent.
    // Guarded so a malformed (non-string) value falls through to `validMacAddress`
    // below and produces the proper "Not a valid username" error rather than a
    // raw TypeError from calling toUpperCase on a number/boolean.
    if (typeof config.bridge.username === 'string') {
      config.bridge.username = config.bridge.username.toUpperCase()
    }
    const username = config.bridge.username
    if (!validMacAddress(username)) {
      throw new Error(`Not a valid username: ${username}. Must be 6 pairs of colon-separated hexadecimal chars (A-F 0-9), like a MAC address.`)
    }

    // Validate the main bridge HAP config (shape + externalsOnly/enabled coherence).
    validateHapConfig(config.bridge, { bridgeLabel: 'main bridge' })

    config.accessories = config.accessories || []
    config.platforms = config.platforms || []

    if (!Array.isArray(config.accessories)) {
      log.error('Value provided for accessories must be an array[]')
      config.accessories = []
    }

    if (!Array.isArray(config.platforms)) {
      log.error('Value provided for platforms must be an array[]')
      config.platforms = []
    }

View on GitHub (pinned to edf5493034)

Solutions

1. Edit config.json so bridge.username is a valid 6-pair colon-separated hex string, e.g. "0E:8F:20:95:9A:1C"
2. Generate a fresh valid username, e.g. run `node -e "console.log([...Array(6)].map(()=>Math.floor(Math.random()*256).toString(16).padStart(2,'0')).join(':').toUpperCase())"`
3. If migrating an old install, copy the original username from the previous config.json or delete the persist/ directory and let Homebridge regenerate it

Example fix

// before (config.json)
"bridge": { "username": "homebridge-mac" }
// after
"bridge": { "username": "0E:8F:20:95:9A:1C" }

const MAC_RE = /^([0-9A-F]{2}:){5}[0-9A-F]{2}$/
if (typeof config.bridge?.username !== 'string' || !MAC_RE.test(config.bridge.username.toUpperCase())) {
  throw new Error('bridge.username must be 6 colon-separated hex pairs, e.g. 0E:8F:20:95:9A:1C')
}

function isValidMacUsername(v: unknown): v is string {
  return typeof v === 'string' && /^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$/.test(v)
}

When it happens

Trigger: config.json `bridge.username` is missing, is a non-string type (number/boolean), has the wrong number of pairs, uses a non-colon separator (e.g. dashes), contains characters outside A-F/0-9, or has mis-sized pairs (e.g. 'AA:BB:CC:DD:EE' with 5 pairs).

Common situations: Hand-edited configs where the username was truncated or pasted without colons; copy-pasting a real MAC with lowercase hex (that is fine, it is uppercased) but with a trailing space or hyphens; configs generated by scripts that wrote a numeric id.

Related errors

• Error loading the ${type} "${identifier}" requested in your
• ${opts.bridgeLabel}: 'hap' must be a boolean or an object wi
• Matter configuration validation failed: ${errors.map(e => `
• Storage path is required for Matter server
• Error loading the ${type} "${identifier}" requested in your

AI-assisted analysis of homebridge/homebridge@edf5493034 (2026-08-30). Data as JSON: /api/errors/8e3a462f2fa25208. Report an issue: GitHub.