Keep media object


One of the most common problems when importing a GEDCOM file into kiwitrees is enabling the “Keep media objects” option. In fact this should almost never (less than 1% of times) be used. It exists only for a very specific group of users.

The result of enabling this option when you don’t require it is that all your media items will no longer be connected to any records (individuals, families, sources etc.) in your tree.

What is a “media object”?

A media object is the reference in a GEDCOM file to a specific media item or file such as an image, a PDF, or video etc.. In the GEDCOM file it will look like this:

0 @[email protected] OBJE
1 FILE grandfather.png
2 FORM
3 TYPE photo

Also in the GEDCOM data are “media links”. These are references like this:

2 OBJE @[email protected]

They tell kiwitrees that this media object (M1001) is linked to this individual or other type of record.

Who are the “very specific group of users”?

Some family history software does not support, and actually deletes media objects, like the one above, from any GEDCOM file use. That used to be fairly common, but is less so today.

Kiwitrees tries to cater for users of most other software products, and allow import / export between them so the “Keep media objects” option is maintained to help users of such software, and ONLY them.

What does enabling “Keep media objects” actually do?

When you import a new, or replacement GEDCOM file into an existing tree the first step is always to delete all the existing GEDCOM data for that tree from your database. That is why, when you start the import routine there is a delay before your computer starts actual importing.

“All existing data” means everything directly related to the GEDCOM file, so all individual, family, source, note, and media records, as well as a few related tables such as the “changes” log and links between records. It is the same process as just deleting that tree from your system. It doesn’t delete files or non-GEDCOM related data. So your media items (files) themselves always remain.

Then the import process starts, taking all the information from the new GEDCOM file and transferring it to the appropriate tables in your database, including re-creating all links between records.

So, if the family history software you used to create that new GEDCOM file changed, or removed the media objects, there is nothing left to tell kiwitrees what items link to which records, so no media can be connected.

By enabling the “Keep media objects” option, when the new GEDCOM file is imported kiwitrees does NOT remove the existing media links, the import process uses those links to recreate the correct media object (that the other software remove or changed), so that the correct connections are re-instated.

What happens if I mistakenly enable “Keep media objects” when I don’t need to?

Because the “Keep media objects” setting tells kiwitrees the incoming GEDCOM file has no media objects, it knows NOT to create any media links. so no attempt is made to re-connect your media file to your data. So you end up with no media being displayed.

Is there a way to fix the issue if I mistakenly used the “Keep media objects” option?

Yes, and it’s quite simple. Just run the import again, using the same GEDCOM file, but without setting the “Keep media objects” option. It will now delete the links, and then accurately recreate them for the GEDCOM media objects it contains, as it should.

Blank page or a “500” error

A blank page indicates that two things happened:

  • A fatal error occured while creating the web page.
  • Your web-server (e.g. apache, nginx, IIS) is configured not to display fatal errors on the screen.

Typical causes of fatal errors are:

  • File permissions. webtrees needs to be able to write to all the files and subfolders in the folder /data/
  • Running out of disk space. You can check if this is a problem by uploading (and then deleting) a large file to the server using FTP.
  • Running out of CPU time. You can identify these because the error does not appear until the time limit is reached.
  • Running out of memory. This can be caused by program errors or by trying to process a lot of data at once. For example, trying to list many thousand individuals at the same time.
  • Incompatible software. For example, using PHP 7.3 with software that was designed for PHP 7.4.
  • Trying to use a PHP function that has been blocked by your web-host. For example, the function needed to send mail can be blocked.

Generally when a fatal error occurs, the web-server will write a detailed error message to a log file. You need to find this error log. Without it, it will be very difficult to fix the problem.

Note that your web-server will produce two log files. One is the access log and the other is the error log. You want the error log.

If you cannot find your error log, you should contact your webhosting provider for assistance.

Alternatively, if your server uses .htaccess files, try adding the following lines:

php_flag display_errors on
php_flag display_startup_errors on
php_value error_reporting -1

ERROR 2: ini_set() has been disabled for security reasons

Disabling ini_set() is not uncommon on some shared servers, but not truly necessary in kiwitrees. It is used in various places to enable admins (only) to adjust things like php memory and time-out settings among others. This error usually appears at the final step of the kiwitrees setup process.

If you web host provides a management tool such as cPanel you can enable functions like this.

Look where you set or change the version of PHP (PHP -> Select version) and then under version what plugins to enable. Then Under “Options” find “disable functions”. Remove ini_set from that disabled functions list.