{"record":{"id":"8e3a462f2fa25208","repo":"homebridge/homebridge","slug":"not-a-valid-username-username-must-be-6-pairs","errorCode":null,"errorMessage":"Not a valid username: ${username}. Must be 6 pairs of colon-separated hexadecimal chars (A-F 0-9), like a MAC address.","messagePattern":"Not a valid username: (.+?)\\. Must be 6 pairs of colon-separated hexadecimal chars \\(A-F 0-9\\), like a MAC address\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"src/server.ts","lineNumber":415,"sourceCode":"    bridge.pin = bridge.pin || defaultBridge.pin\n    config.bridge = bridge\n\n    // Validate Matter port pool configuration. Must run after bridge defaults\n    // are filled in, since the cast to HomebridgeConfig only becomes honest at\n    // that point.\n    MatterConfigCollector.validateMatterPortsPool(config as HomebridgeConfig)\n\n    // Normalise the main bridge username to uppercase so downstream comparisons\n    // (validMacAddress, registry lookups, child-bridge dedup) stay case-consistent.\n    // Guarded so a malformed (non-string) value falls through to `validMacAddress`\n    // below and produces the proper \"Not a valid username\" error rather than a\n    // raw TypeError from calling toUpperCase on a number/boolean.\n    if (typeof config.bridge.username === 'string') {\n      config.bridge.username = config.bridge.username.toUpperCase()\n    }\n    const username = config.bridge.username\n    if (!validMacAddress(username)) {\n      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.`)\n    }\n\n    // Validate the main bridge HAP config (shape + externalsOnly/enabled coherence).\n    validateHapConfig(config.bridge, { bridgeLabel: 'main bridge' })\n\n    config.accessories = config.accessories || []\n    config.platforms = config.platforms || []\n\n    if (!Array.isArray(config.accessories)) {\n      log.error('Value provided for accessories must be an array[]')\n      config.accessories = []\n    }\n\n    if (!Array.isArray(config.platforms)) {\n      log.error('Value provided for platforms must be an array[]')\n      config.platforms = []\n    }\n","sourceCodeStart":397,"sourceCodeEnd":433,"githubUrl":"https://github.com/homebridge/homebridge/blob/edf54930340d67cade23d01abd41b03cd9621e8b/src/server.ts#L397-L433","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Edit config.json so bridge.username is a valid 6-pair colon-separated hex string, e.g. \"0E:8F:20:95:9A:1C\"","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())\"`","If migrating an old install, copy the original username from the previous config.json or delete the persist/ directory and let Homebridge regenerate it"],"exampleFix":"// before (config.json)\n\"bridge\": { \"username\": \"homebridge-mac\" }\n// after\n\"bridge\": { \"username\": \"0E:8F:20:95:9A:1C\" }","handlingStrategy":"validation","validationCode":"const MAC_RE = /^([0-9A-F]{2}:){5}[0-9A-F]{2}$/\nif (typeof config.bridge?.username !== 'string' || !MAC_RE.test(config.bridge.username.toUpperCase())) {\n  throw new Error('bridge.username must be 6 colon-separated hex pairs, e.g. 0E:8F:20:95:9A:1C')\n}","typeGuard":"function isValidMacUsername(v: unknown): v is string {\n  return typeof v === 'string' && /^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$/.test(v)\n}","tryCatchPattern":null,"preventionTips":["Generate usernames with a script instead of hand-typing them","Keep one canonical config.json under version control and edit only values, not structure","Validate config.json with a JSON schema before deploying (homebridge-config-ui-x does this)"],"tags":["config","validation","startup","mac-address"],"backgroundTag":"invalid-mac-username","analyzedSha":"edf54930340d67cade23d01abd41b03cd9621e8b","analyzedAt":"2026-08-30T21:28:53.235Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}