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

Check the application/database error logs for the underlying SQL exception raised during save().

passbolt/passbolt_api · critical · Cake\Http\Exception\InternalErrorException

Could not save the folder history.

Error message

Could not save the folder history.

What it means

After validation passes, FoldersHistoryTable::create() calls save(); when save() returns false (the entity could not be persisted), an InternalErrorException with 'Could not save the folder history.' is thrown. This indicates a persistence-level failure rather than a validation problem.

Solutions

Check the application/database error logs for the underlying SQL exception raised during save().
Verify the folders_history table schema is up to date (run migrations, e.g. `ddev refresh` or cake migrations migrate).
Confirm database connectivity and that the storage backend (MySQL/MariaDB/Postgres) is healthy.
Check for unique/constraint conflicts on folder_id and handle retries or deduplication in the calling code.

Example fix

// before
$folderHistory = $this->save($folderHistory); // silent false -> InternalError
// after
$folderHistory = $this->save($folderHistory);
if (!$folderHistory) {
    $this->log('Folder history save failed: ' . json_encode($folderHistory->getErrors()), 'error');
    throw new InternalErrorException('Could not save the folder history.');
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    $foldersHistoryTable->create($data);
} catch (InternalErrorException $e) {
    // log DB errors, verify schema/migrations and connectivity, then retry or alert
    Log::error('Folder history persistence failed: ' . $e->getMessage());
}

Prevention

Run database migrations after every deployment so folders_history schema matches the model.
Monitor database connectivity and lock/timeout metrics in production.
Log the underlying PDO/SQL exception when save() returns false to expose the root cause.
Handle concurrent writes to the same folder id to avoid unique constraint conflicts.

When it happens

Trigger: save() on the FoldersHistory entity returns false — typically a database-level failure: duplicate primary key on folder_id/id mapping, constraint violations not caught by validation, database connection issues, or transaction/locking problems.

Common situations: Database down or migration missing (folders_history table absent/outdated schema), unique constraint collisions when the same folder id is written concurrently, or storage backend (MySQL/Postgres) rejecting the insert due to column length/encoding.

Related errors

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

Appendix: source

Thrown at plugins/PassboltCe/Folders/src/Model/Table/FoldersHistoryTable.php:173

     * @throws \App\Error\Exception\ValidationException
     * @throws \Cake\Http\Exception\InternalErrorException
     */
    public function create(array $data): FolderHistory
    {
        // Folder.Id becomes FolderHistory.FolderId
        $data['folder_id'] = $data['id'];
        unset($data['id']);

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

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

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

        return $folderHistory;
    }
}

View on GitHub (pinned to 31c1bbc10f)