Troubleshooting Common Omeka Issues

This guide provides a summary of common troubleshooting tips for working with the Omeka Content Management System (Omeka Classic). Whether you're dealing with file upload issues, database errors, or configuration problems, this document outlines the essential steps and points you to detailed guides for each situation.

Creating a User Account Directly via the Database

If you've lost access to your Omeka admin account and password reset options aren't working, you can manually create a new admin user by inserting a record into the database.

Here is an overview of the process:

1. Log into your cPanel > Databases section, and open phpMyAdmin.
2. Identify the database associated with your Omeka installation. If unsure, you can find the database name under the Installatron Application settings > Advanced tab.
3. Within the database, select the users table. Locate an existing Super User profile and use the "Copy" function to duplicate it.
4. In the copied entry, update the username and email fields with your desired credentials. Leave other fields as they are.
5. Save the changes.
6. Navigate to your Omeka site's login page, click on "Lost your password?", and enter the email address you specified earlier.
7. Follow the instructions in the password reset email to set a new password.

Full Guide: Creating Omeka User from the Database

Enable Error Logging in Omeka (Classic and S)

If you're experiencing unexplained issues in Omeka, enabling error logging is a critical first step. This allows you to capture detailed error messages, which can help diagnose and resolve problems more efficiently.

Here is an overview of the process:

1. Update File Manager Settings: Update your File Manager to show hidden files.
2. Edit the .htaccess File: Find the following line, and remove the # sign: #SetEnv APPLICATION_ENV development so that it reads: SetEnv APPLICATION_ENV development.

Once that’s done, reload your site and you should see an in-depth error on the page.

Full Guide: Enable Error Logging in Omeka Classic and Omeka S

Fixing Background PHP Path for Omeka and Omeka S

Some plugins for Omeka will require that you explicitly specify the background PHP path in order to work properly, as these plugins require PHP-CLI. We have a dedicated guide on fixing this here:

Fixing Background PHP Path for Omeka and Omeka S

ImageMagick Not Working in Omeka

Omeka relies on ImageMagick for image processing. If you're seeing broken thumbnails or errors when uploading images, ImageMagick may not be configured correctly.

1. To generate thumbnails and derivative images in Omeka, set the ImageMagick path under Settings > General using /opt/rh-imagemagick/bin.
2. After saving the path, new images will generate thumbnails.
3. To regenerate thumbnails for previously uploaded items, use the Derivative Images plugin.

Full Guide: ImageMagick in Omeka

Upload File Size Limits in Omeka

If you're getting errors when uploading large files or media, your PHP environment may be restricting file sizes. To increase the file size limits:

1. Access your Omeka installation's config.ini file, typically located at /application/config/config.ini.

2. Open the file and locate the line upload.maxFileSize = "10M".

3. Uncomment this line if it's commented out (remove the leading ;) and adjust the value to your desired upload limit (e.g., "50M").

4. Save the changes.

Full Guide: Increasing Omeka Upload File Limits

File Upload Errors: The given destination is not writable 

If you encounter the error Zend_File_Transfer_Exception: The given destination is not writable while uploading files, you can resolve it by manually setting a temporary storage directory:

1.  Log into cPanel and open File Manager.
2. Navigate to your Omeka directory: application/config/config.ini.
3. In the config.ini file, find the Storage section and add:

   storage.tempDir = "/home/username/tmp"
   (Replace username with your actual cPanel username)

4. Save the file and try uploading again.

This change directs Omeka to use a writable temp directory for file uploads.

Full Guide: Omeka Error: Given Destination Is Not Writable

Neatline Plugin: Database Requirements and Errors

If you're using the Neatline plugin for Omeka Classic and run into errors, it's likely related to database compatibility. Neatline requires specific versions of MySQL and database engines to function properly.

• Neatline stores geometry data that may be incompatible with MySQL versions 5.7 and above.

• Sites using Neatline with MySQL versions prior to 5.7 may encounter errors or data loss when upgrading or migrating.

• To prevent issues, disable automatic updates in Installatron.

• If problems occur, restoring the site and database from a backup may be necessary.

• Updating or recreating Neatline maps using MySQL 5.7 or later is recommended for future compatibility.

Full guide: Neatline for Omeka: Database Requirements and Issues

Need More Help?

For more technical documentation, visit the Omeka Support Portal.