{"record":{"id":"b1228f6237f83efa","repo":"passbolt/passbolt_api","slug":"a-mapping-rule-for-username-attribute-could-not-be-found-for","errorCode":null,"errorMessage":"A mapping rule for username attribute could not be found for directory type: {0}","messagePattern":"A mapping rule for username attribute could not be found for directory type: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":500,"severity":"error","filePath":"plugins/PassboltEe/DirectorySync/src/Utility/DirectoryEntry/DirectoryResults.php","lineNumber":241,"sourceCode":"\n        return $this->_transformEmail($ldapUser);\n    }\n\n    /**\n     * Transform ldap object email based on provided configuration.\n     *\n     * @param \\LdapRecord\\Models\\Entry $ldapUser ldap user\n     * @return \\LdapRecord\\Models\\Entry\n     * @throws \\RuntimeException A mapping rule for username attribute could not be found for the directory type\n     */\n    protected function _transformEmail(Entry $ldapUser): Entry\n    {\n        /** @var string $directoryType */\n        $directoryType = $ldapUser->getFirstAttribute('directoryType');\n        $mappingRules = $this->mappingRules[$directoryType] ?? [];\n        $emailAttribute = $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['username'] ?? null;\n        if (!$emailAttribute) {\n            throw new RuntimeException(\n                __('A mapping rule for username attribute could not be found for directory type: {0}', $directoryType)\n            );\n        }\n        $useEmailPrefixSuffix = $this->directorySettings->getUseEmailPrefixSuffix();\n\n        if (!$ldapUser->hasAttribute($emailAttribute) && $useEmailPrefixSuffix) {\n            $emailPrefix = $this->directorySettings->getEmailPrefix();\n            $prefix = $ldapUser->getFirstAttribute($emailPrefix);\n            $suffix = $this->directorySettings->getEmailSuffix();\n            $ldapUser->setAttribute($emailAttribute, $prefix . $suffix);\n        }\n\n        return $ldapUser;\n    }\n\n    /**\n     * Adds a uuid to the ldap object if not present and if a dn exists.\n     *","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/plugins/PassboltEe/DirectorySync/src/Utility/DirectoryEntry/DirectoryResults.php#L223-L259","documentation":"DirectoryResults::_transformEmail resolves the LDAP attribute that holds the user's username/email from mappingRules[directoryType]['user']['username']. If that key is missing or empty it cannot build the user's email and throws a RuntimeException naming the directory type.","triggerScenarios":"Transforming an LDAP user whose directoryType (e.g. 'ad', 'openldap', 'openldap Racing') has no ['user']['username'] mapping rule in the directory settings mapping rules array.","commonSituations":"Migration from the legacy DirectorySync settings format where mapping rules were stored differently; manually edited directory settings JSON dropping the username key; unsupported directory type value returned by the LDAP server.","solutions":["Re-save directory sync settings so the default mapping rules for the detected directory type are regenerated","Verify mappingRules[directoryType]['user']['username'] exists for the directoryType reported in the error","Correct the directoryType attribute/configuration if the LDAP server reports an unexpected directory type","Configure the email/username attribute explicitly in the admin LDAP settings form"],"exampleFix":"// before\n$emailAttribute = $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['username'] ?? null;\nif (!$emailAttribute) {\n    throw new RuntimeException(\n        __('A mapping rule for username attribute could not be found for directory type: {0}', $directoryType)\n    );\n}\n// after\n$emailAttribute = $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['username']\n    ?? $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['mail']\n    ?? null;\nif (!$emailAttribute) {\n    throw new RuntimeException(\n        __('A mapping rule for username attribute could not be found for directory type: {0}', $directoryType)\n    );\n}","handlingStrategy":"validation","validationCode":"$rules = $mappingRules[$directoryType]['user'] ?? [];\nif (empty($rules['username'])) { throw new DomainException('Configure username mapping before sync'); }","typeGuard":"$emailAttribute = $mappingRules[$directoryType]['user']['username'] ?? null;\nif (!is_string($emailAttribute) || $emailAttribute === '') { return null; }","tryCatchPattern":"try {\n    $results->transformLdapUser($ldapUser);\n} catch (RuntimeException $e) {\n    $this->log($e->getMessage());\n    // re-save directory settings to restore default mappings, then retry\n}","preventionTips":["Re-save LDAP settings from the admin UI after upgrades to regenerate default mappings","Never hand-edit the mapping-rules portion of directory settings JSON","Confirm the directoryType attribute matches a supported directory type"],"tags":["ldap","mapping","configuration","email"],"backgroundTag":"missing-config-key","analyzedSha":"31c1bbc10f32808a607fa9bd81891e898779c0bc","analyzedAt":"2026-09-17T00:04:38.960Z","contentChangedAt":"2026-09-17T00:04:38.960Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}