Troubleshooting

FAQs#

Does PageVersioning capture every save automatically? Yes. Every page create and update triggers an automatic snapshot. No manual action is needed. The module hooks into Omeka S's entity lifecycle events, so any save—whether triggered by the page editor, a module, or the API—is captured.

Does it capture changes to individual content blocks? Yes. The module listens for changes to both the page entity and its block entities. If only a block's content changes (without the page title or slug changing), a version is still captured.

What happens if I save a page multiple times in one request? The module includes per-request deduplication. Even if Omeka S flushes the page entity and its block entities separately in a single HTTP request, only one version snapshot is created.

What happens to versions when a page is deleted? Version records are preserved in the database as an audit trail. They remain accessible through the global audit log. The snapshot view gracefully handles pages that no longer exist.

Will the module slow down page saves? The overhead is minimal. The module performs a single database insert per page save and (if retention is enabled) occasionally deletes old rows. There is no file I/O or external service call involved.

Can I change the retention limit after the module is already in use? Yes. Changing the retention limit takes effect on the next page save. If you lower the limit, excess versions for a page will be pruned the next time that page is saved. Existing pages that haven't been edited will retain their current version count until their next save.

Is the version data included in Omeka S backups? The page_versions table is a standard MySQL/MariaDB table. Any database backup that includes all tables will capture version data. Omeka S's built-in export tools do not include this table, so ensure your backup process covers the full database.

Can I use PageVersioning with Omeka S 3.x and 4.x? Yes. The module is compatible with both Omeka S 3.0+ and 4.0+.

Does the module have any external PHP dependencies? No. PageVersioning uses only Omeka S's built-in libraries and a pure-PHP diff algorithm. There are no Composer dependencies beyond Omeka S itself.

Troubleshooting#

Versions are not being captured

• Confirm the module is installed and active under Modules in the admin panel.
• Check that the page_versions database table exists. If it does not, try uninstalling and reinstalling the module.
• Look for errors in the PHP error log. Version capture failures are logged as [PageVersioning] captureVersion failed: ... but are intentionally silenced so they never block a page save.

The "Version history" button does not appear on the page edit screen

• Ensure you are editing a site page (not an item, item set, or other resource). PageVersioning only tracks site pages.
• Verify the module is active. Navigate to Modules and confirm the status shows as active.

I cannot revert a page

• Reverting requires the Editor role or higher. Reviewers and Authors can only view version history.
• Ensure the revert form's CSRF token has not expired. If you left the page open for a long time, reload the snapshot view and try again.

The diff shows no changes between two versions

• The diff compares the text content of blocks with HTML tags stripped. If the only changes were to HTML formatting (e.g., making text bold) without changing the actual text, the diff may appear empty.
• Metadata changes (title, slug, visibility) are included in the diff. If those are unchanged and the text content is identical, the similarity will be 100%.

The retention policy does not seem to be working

• Retention is enforced per-page on each save. If you lower the retention limit, old versions are only pruned the next time that specific page is saved.
• A retention limit of 0 means keep everything. Verify the setting is not set to 0 if you expect pruning.

"No versions recorded yet" appears for a page that has been edited

• Versions are only captured for edits made after the module was installed. The module does not retroactively create versions for past edits.

API requests return 403 Forbidden

• Ensure your request includes valid authentication. Use either an active admin session (cookie-based) or provide key_identity and key_credential query parameters with a valid Omeka S API key.
• The API key must belong to a user with at least the Author role to read version data, or the Editor role to revert.

Database table is missing after an upgrade

• If upgrading from a very early version, the install SQL may need to be re-run. Back up your data, then try uninstalling and reinstalling the module through the admin panel. Note that uninstalling drops the page_versions table and all stored data.