FAQs

Troubleshooting

Who can access the Backup module?

Only users with the Global Administrator or Supervisor (site admin) role. Every other role gets an HTTP 403 Access Denied page on /admin/backup and a permission error from /api/backups. 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 action streams the file with PHP's readfile() after clearing output buffers, which works on any server without configuration. There is no built-in X-Sendfile support; for very large archives, copy the file from the backup directory directly instead.

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