What causes "Could not save the entity history." in passbolt/passbolt_api?

Check application and database error logs for the underlying save failure cause.

passbolt/passbolt_api · error · InternalErrorException

Could not save the entity history.

Error message

Could not save the entity history.

What it means

EntitiesHistoryTable::create() throws this InternalErrorException when save() returns false without validation errors — a raw persistence failure. The entity history row could not be written to the database even though the data was valid.

Solutions

Check application and database error logs for the underlying save failure cause.
Run pending migrations so the entity history schema matches the plugin version.
Verify DB connectivity and that the connection is not read-only.
Audit event listeners on Model.beforeSave for EntitiesHistory that may return false without errors.

Example fix

// before
$entityHistory = $this->save($log, ['associated' => ['PermissionsHistory']]);
if (!$entityHistory) {
    throw new InternalErrorException('Could not save the entity history.');
}
// after
$entityHistory = $this->save($log, ['associated' => ['PermissionsHistory']]);
if (!$entityHistory) {
    $this->log('Entity history save failed: ' . json_encode($log->getErrors()), 'error');
    throw new InternalErrorException('Could not save the entity history.');
}

Defensive patterns

Strategy: try-catch

Validate before calling

try { $this->EntitiesHistory->getConnection()->query('SELECT 1'); } catch (\Throwable $e) { // DB unavailable }

Type guard

null

Try / catch

try { $entitiesHistoryTable->create($data); } catch (InternalErrorException $e) { Log::error('Entity history save failed: ' . $e->getMessage()); // degrade gracefully, do not fail the main operation
}

Prevention

Run migrations on every deployment.
Monitor DB locks and long-running transactions during bulk operations.
Avoid wrapping many history writes in one long transaction.
Audit beforeSave listeners for silent false returns.

When it happens

Trigger: Valid entity history data but the INSERT fails: DB connection loss, missing entity_history table/columns after partial migration, lock wait timeout, or a beforeSave listener aborting silently.

Common situations: Migrations missing after a passbolt upgrade; database under heavy load during bulk operations that write many history rows; replication/readonly connection misconfiguration; disk-full on the DB host.

Related errors

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

Appendix: source

Thrown at plugins/PassboltCe/Log/src/Model/Table/EntitiesHistoryTable.php:212

        ];
        $data = array_merge($defaultData, $data);

        // Check validation rules.
        $log = $this->buildEntity($data);
        if ($log->getErrors()) {
            throw new ValidationException(__('Could not validate entity history data.', true), $log, $this);
        }

        $entityHistory = $this->save($log, ['associated' => ['PermissionsHistory']]);

        // Check for validation errors. (associated models too).
        if ($log->getErrors()) {
            throw new ValidationException(__('Could not validate entity history data.'), $entityHistory, $this);
        }

        // Check for errors while saving.
        if (!$entityHistory) {
            throw new InternalErrorException('Could not save the entity history.');
        }

        return $entityHistory;
    }
}

View on GitHub (pinned to 31c1bbc10f)