FAQs Omeka S module

Troubleshooting

Who can access the Backup module?

Only users with the Global Administrator role. Supervisors could use it before 1.4.2 and no longer can. Other roles do not see the Backup menu; opening a Backup page shows Omeka's Forbidden page (HTTP 403), and /api/backups returns a permission error. Before 1.4.3 they got Omeka's error page Omeka S encountered an error (HTTP 500) instead. See Configuration.

The backup directory is not writable

The Settings page shows Not writable or Directory does not exist next to the current path. Create the directory and give the web server user write access:

mkdir -p /var/backups/omeka
chown www-data:www-data /var/backups/omeka
chmod 750 /var/backups/omeka

Then enter the path under Admin > Backup > Settings and save. Leave the field blank to use OMEKA_PATH/backup.

I clicked Create Backup but the list shows no new archive, or the status is "failed"

The backup runs as a background job. Open Admin > Jobs and look at the most recent Backup\Job\BackupJob entry; its log holds the error. The module's own backup.log in the backup directory has the same message. Common causes:

  • The backup directory does not exist or is not writable.
  • Less than 100 MB is free in the backup directory. The module checks this before starting.
  • The system temporary directory ran out of space. The archive is assembled there first, so it needs room for an uncompressed copy of everything selected.
  • Another backup was already running (see below).

Delete the failed record with Delete once you have fixed the cause.

The job stays at "starting" or "in progress" and never finishes

If the job never produces any log output, Omeka S could not start the PHP CLI process that runs jobs. Check the cli section of config/local.config.php (phpcli_path and execute_strategy) and confirm the PHP binary works from the command line. The job page under Admin > Jobs reports the underlying error when the process fails to launch.

If the process was killed part-way (server restart, out-of-memory), the record stays at in_progress. Delete it from the list; the lock file is released when the process exits, but see the next question if it was not.

"Another backup operation is already in progress"

Only one backup can run at a time. The module holds an exclusive lock on .backup.lock in the backup directory while a backup runs. The lock is released automatically when the process ends, even after a crash, because the operating system drops it when the file handle closes. If the message persists with no job running, check for a leftover PHP process, then remove the file:

rm /path/to/backup/dir/.backup.lock

Restore aborted with "checksum mismatch"

The ZIP on disk no longer matches the SHA-256 digest recorded when it was created, uploaded or added. The file was modified, truncated or corrupted. Replace it with a good copy: upload it again, or delete the record, copy the archive into the backup directory again and click Add to backups. Either way a fresh checksum is recorded for the new copy.

Restore stopped with "The archive is damaged" or "Not enough free space"

Both are checked after the archive is unpacked into the system temporary directory and before anything on the site changes, so the message ends with Nothing was restored.

  • The archive is damaged: … does not match the checksum stored in the ZIP names a file inside the archive that was corrupted, usually by an incomplete or ASCII-mode transfer. Bring a good copy across and try again.
  • Not enough free space in … to unpack the archive means the temporary directory cannot hold the uncompressed contents. Free up space there, or point PHP's temporary directory (sys_temp_dir in php.ini, or the TMPDIR environment variable of the process that runs jobs) at a larger disk. The restore preview shows this warning before you start.

Backups created recently vanished from the list after a restore

The database dump includes the module's own omeka_backup table, so restoring a database puts the list back to the state it was in when that archive was made. The archives are still in the backup directory: they appear under Archives in the backup directory on the Backups page, where Add to backups lists them again. See Restoring Backups.

Upload fails with "exceeds the maximum allowed size"

The limit comes from PHP's upload_max_filesize and post_max_size (and sometimes a web server body size limit), not from the module. Copy the archive into the backup directory with FTP, SFTP or SSH instead and add it from the Backups page: see Adding Archives by FTP. Alternatively raise those PHP values and restart PHP, or create the backup with fewer components so the archive is smaller.

I copied a ZIP into the backup directory but it does not appear

The Backups page lists only files that:

  • are directly in the backup directory shown on Admin > Backup > Settings, not in a subfolder;
  • end in .zip (any capitalisation) and do not start with a dot. Some FTP clients write to a temporary name such as archive.zip.filepart or .archive.zip and rename the file when the transfer is complete;
  • are not already in the backup list under the same path.

The Archives in the backup directory section only appears when there is at least one such file.

A backup in the list shows "file missing"

The record is complete but its ZIP is no longer at the recorded path: it was deleted or moved outside the module, the storage path setting changed, or the record came from another server's database in a restore. Download and Restore are hidden for it. Delete the record, or put the archive back at its path. See Moving to a New Server.

Upload rejected: "does not appear to be an Omeka S backup (missing metadata.json)"

metadata.json must be at the top level of the ZIP. This usually happens when an archive was unzipped and re-zipped with an extra parent folder, or when the file is not a backup made by this module. See Backup Archive Format.

How do I keep backups small or fast?

Untick Include files (files/ directory), and if you do not need them, the themes and modules directories. The database dump and API export are usually small. You can back up files/ separately with rsync on its own schedule. From the CLI, use create --no-files; themes and modules cannot be excluded there.

Are private items in the API export?

From the admin panel, yes: the export runs as the user who started the backup, and administrators see everything. From cron or the CLI there is no logged-in user, so only public resources are exported. db.sql always contains every row regardless. Also note that export/files.json is empty in the current version; media are covered by the database dump.

Can I use the API export to restore resources?

Not with this module. The export/ folder is an informational snapshot; the restore only applies db.sql, files/, themes/ and modules/. To load JSON-LD into another site, use an import tool such as the CSV Import or Bulk Import modules.

Can downloads use X-Sendfile or X-Accel-Redirect?

The Download button and download links stream the file from PHP in 1 MB pieces after clearing output buffers, which works on any server without configuration, and they serve byte ranges, so an interrupted download can continue where it stopped. There is no built-in X-Sendfile support. To move a very large archive to another server, a download link lets that server fetch it directly (see Download Links); or copy the file from the backup directory.

"The archive could not be stored in the site's file store"

The backup was made, but the cloud file store refused it; the message ends with the store's reason. The record is marked failed and the archive stays in the private folder on the server: delete the record to remove it. Until the store works, enter a Backup storage path under Settings to keep archives on the server. See Sites with Cloud File Storage.

"The archive could not be copied from the site's file store" or "could not be read from the site's file store"

A restore copies an archive kept in the cloud file store to the server first, and a download passes it through the site. HTTP 404 (or 403 on some stores) means the archive is no longer in the store: it was deleted there by hand, the store's settings changed, or the record came from another site's database in a restore. Delete the record. Other errors are tried again first.

"None of the site's files could be downloaded from its file store"

A backup on a site whose files are in cloud storage reads each file from the address the store gives for it, and the store answered not found or forbidden for every one. Check that the site's images show on its public pages: if they do not, the store's address settings are wrong. Backup cannot back up files from a store that does not serve them.

Does uninstalling delete my archives?

No. Uninstalling drops the omeka_backup table and removes the two settings; the ZIP files, backup.log and lock file stay in the backup directory. After a reinstall they appear under Archives in the backup directory, ready to add back. See Installation.

Log in for Support