passbolt/passbolt_api · error · UnexpectedValueException

Directory Settings are invalid. Please check your config…

Error message

Directory Settings are invalid. Please check your config and try again.

What it means

UpdateDirectorySettingsService::updateSettings() migrates old (v3-format) directory sync organization settings to the v4 format (renaming ldap.domains.*.servers to hosts, etc.). It first json_decodes the stored settings value and throws this UnexpectedValueException if the result is empty, false (invalid JSON), or not an array — i.e. the stored settings cannot be parsed into the expected structure.

Solutions

Inspect the stored value: SELECT value FROM organization_settings WHERE property = 'directory-sync'; and validate it with json_decode.
Fix or regenerate the settings by re-saving LDAP configuration in the passbolt admin UI.
If unrecoverable, delete the settings row and reconfigure directory sync from scratch in v4.
Restore the row from a pre-upgrade backup if the corruption happened during migration.

Defensive patterns

Strategy: validation

Validate before calling

$raw = $settings->value;
$decoded = json_decode($raw, true);
if (!$decoded || !is_array($decoded)) { /* abort: invalid stored settings */ }

Type guard

$hasValidSettingsJson = fn(?OrganizationSetting $s): bool => $s && ($v = json_decode($s->value, true)) && is_array($v);

Try / catch

try {
    (new UpdateDirectorySettingsService())->updateSettings();
} catch (UnexpectedValueException $e) {
    // stored value is not valid JSON — restore from backup or reconfigure LDAP settings
}

Prevention

Validate the stored JSON before running upgrade/migration services
Back up organization_settings before v3→v4 upgrades
Re-save directory sync settings via the admin UI rather than editing the DB
Check value column integrity (truncation/charset) after DB restores

When it happens

Trigger: Running the settings update during a v3→v4 upgrade when the organization_settings value column for directory sync contains invalid JSON, an empty string, or a scalar (e.g. '0', 'null', serialized-but-not-JSON data).

Common situations: Upgraded passbolt where the settings row was written by a much older version in a different format; manual DB edits that broke the JSON; truncated value column; charset/encoding corruption during a DB dump/restore.

Related errors

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

Appendix: source

Thrown at plugins/PassboltEe/DirectorySync/src/Service/DirectorySettings/UpdateDirectorySettingsService.php:51

     */
    public function updateSettings(): void
    {
        /** @var \App\Model\Table\OrganizationSettingsTable $OrganizationSettings */
        $OrganizationSettings = $this->fetchTable('OrganizationSettings');
        /** @var \App\Model\Entity\OrganizationSetting|null $directorySyncSettings */
        $directorySyncSettings = $OrganizationSettings
            ->find()
            ->where([
                'property' => DirectoryOrgSettings::ORG_SETTINGS_PROPERTY,
            ])->first();

        if (!$directorySyncSettings) {
            return;
        }

        $value = json_decode($directorySyncSettings['value'], true);
        if (!$value || !is_array($value)) {
            throw new UnexpectedValueException(
                __('Directory Settings are invalid. Please check your config and try again.')
            );
        }
        // set the new key for list of servers/hosts in the new library
        if (is_array($value['ldap']['domains'])) {
            foreach ($value['ldap']['domains'] as $domain => $config) {
                if (array_key_exists('servers', $config)) {
                    $value['ldap']['domains'][$domain]['hosts'] = $config['servers'];
                    unset($value['ldap']['domains'][$domain]['servers']);
                }
            }
        }

        // keep compatibility with old library default class value
        if (empty($value['groupObjectClass'])) {
            $value['groupObjectClass'] = 'groupOfNames';
        }
        $value['enabled'] = false;

View on GitHub (pinned to 31c1bbc10f)