passbolt/passbolt_api · error · RuntimeException

A mapping rule for username attribute could not be found…

Error message

A mapping rule for username attribute could not be found for directory type: {0}

What it means

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.

Solutions

1. Re-save directory sync settings so the default mapping rules for the detected directory type are regenerated
2. Verify mappingRules[directoryType]['user']['username'] exists for the directoryType reported in the error
3. Correct the directoryType attribute/configuration if the LDAP server reports an unexpected directory type
4. Configure the email/username attribute explicitly in the admin LDAP settings form

Example fix

// before
$emailAttribute = $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['username'] ?? null;
if (!$emailAttribute) {
    throw new RuntimeException(
        __('A mapping rule for username attribute could not be found for directory type: {0}', $directoryType)
    );
}
// after
$emailAttribute = $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['username']
    ?? $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['mail']
    ?? null;
if (!$emailAttribute) {
    throw new RuntimeException(
        __('A mapping rule for username attribute could not be found for directory type: {0}', $directoryType)
    );
}

$rules = $mappingRules[$directoryType]['user'] ?? [];
if (empty($rules['username'])) { throw new DomainException('Configure username mapping before sync'); }

$emailAttribute = $mappingRules[$directoryType]['user']['username'] ?? null;
if (!is_string($emailAttribute) || $emailAttribute === '') { return null; }

try {
    $results->transformLdapUser($ldapUser);
} catch (RuntimeException $e) {
    $this->log($e->getMessage());
    // re-save directory settings to restore default mappings, then retry
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• A mapping rule for ID attribute could not be found for…
• Mapping rules could not be found for directory type
• There is no mapping rule associated for the field:
• 500
• An error has occurred parsing groupCustomFilter

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/b1228f6237f83efa. Report an issue: GitHub.

Appendix: source

Thrown at plugins/PassboltEe/DirectorySync/src/Utility/DirectoryEntry/DirectoryResults.php:241

        return $this->_transformEmail($ldapUser);
    }

    /**
     * Transform ldap object email based on provided configuration.
     *
     * @param \LdapRecord\Models\Entry $ldapUser ldap user
     * @return \LdapRecord\Models\Entry
     * @throws \RuntimeException A mapping rule for username attribute could not be found for the directory type
     */
    protected function _transformEmail(Entry $ldapUser): Entry
    {
        /** @var string $directoryType */
        $directoryType = $ldapUser->getFirstAttribute('directoryType');
        $mappingRules = $this->mappingRules[$directoryType] ?? [];
        $emailAttribute = $mappingRules[DirectoryInterface::ENTRY_TYPE_USER]['username'] ?? null;
        if (!$emailAttribute) {
            throw new RuntimeException(
                __('A mapping rule for username attribute could not be found for directory type: {0}', $directoryType)
            );
        }
        $useEmailPrefixSuffix = $this->directorySettings->getUseEmailPrefixSuffix();

        if (!$ldapUser->hasAttribute($emailAttribute) && $useEmailPrefixSuffix) {
            $emailPrefix = $this->directorySettings->getEmailPrefix();
            $prefix = $ldapUser->getFirstAttribute($emailPrefix);
            $suffix = $this->directorySettings->getEmailSuffix();
            $ldapUser->setAttribute($emailAttribute, $prefix . $suffix);
        }

        return $ldapUser;
    }

    /**
     * Adds a uuid to the ldap object if not present and if a dn exists.
     *

View on GitHub (pinned to 31c1bbc10f)