Installation-Troubleshooting

This document presents solutions & tips for installation-related problems, and for things that don't seem to be working correctly after installation.

Other issues are discussed on the generic Troubleshooting page.

If you experience any problems while installing refbase, please read this chapter before contacting us.

Preparations before contacting us

In few cases, the refbase installation shows an unwanted behaviour. This may be caused by special settings of your server setup.

Important: Please check following settings and REPORT THEM when contacting us. This information will help us a lot to figure out what might be wrong:

• Which version of refbase do you use?
• Which platform are you using?
• Do you use a particular package such as XAMPP?
• Which versions of Apache, MySQL and PHP are you running?
• Can you execute other PHP web applications just fine? I.e., is it only refbase that is causing you trouble?
• Can you access MySQL correctly, from the command line as well as from web administration tools such as phpMyAdmin?
• Do you experience the same error/problem using a different browser or computer?
• Do you know about special config settings within your httpd.conf, php.ini or my.cnf configuration files?
• Compare your php.ini with the list of required php.ini settings and report any differences.
• Regarding php.ini settings, especially verify that safe_mode is OFF for installation. If you can't change this setting, you may need to perform a manual installation.
• Have a look at your server's error log and report anything that may be connected with refbase.
• Please make sure that PHP error reporting is enabled and report any error messages displayed in your browser. To enable error reporting, set the following variables in your php.ini file:

error_reporting  =  E_ALL
display_errors = On

General tips

Please ensure that you have checked the following:

• If you're using an older refbase version, you may want to update to the newest version and see if this cures your problems.
• If you receive errors when using refbase (e.g., when adding or importing data), please try the same procedure in our demo databases to check, whether this problem is specific to your own installation/data or whether it's a general issue.
• Make sure that you've restarted your web server to apply any changes you've made to your php.ini file.
• Some installations come with multiple php.ini copies at different locations. To make sure that you're dealing with the correct php.ini file, checkout the output of the phpinfo() function, it will tell you the location of the active php.ini file (more info). The returned status info may contain other useful information and it may help to send us the output via private mail.
• If your package manager separates php-mysql from the main php-package (eg. Fedora) make sure to install both. Otherwise every request to refbase will give an empty white page.
• Make sure that the refbase scripts have correct permission settings so that they can be accessed by your server.

Known problems and possible solutions

Fail to login

If you have problems to log in with your newly created user account after installing refbase, please refer to Creating the first user.

Upload of large files fails

If you're able to upload files of small file size but experience errors when attempting to upload large files, checkout the variables post_max_size and upload_max_filesize in your active php.ini file. The values given for post_max_size and upload_max_filesize must be larger than the maximum file size you'd like to be able to upload (see also required php.ini settings).

Upload of files under XAMPP doesn't work

In some versions of XAMPP the default temporary folder for uploads, as defined in php.ini, is wrong:

upload_tmp_dir = ".;c:\apachefriends\xampp\tmp"

correct would be:

upload_tmp_dir = "c:\apachefriends\xampp\tmp"

Renaming of uploaded files does not work under XAMPP

In some versions of XAMPP the needed PHP function iconv is disabled. To fix this, open the php.ini file of your XAMPP distribution, search for iconv and enable the function by deleting the heading comment sign (').

Export of records results in a blank page

At present, the ADS, BibTeX, EndNote, ISI, RIS and Word XML export formats require a correctly configured Bibutils while any of the other XML formats (e.g. MODS XML or ODF XML) do not depend on Bibutils. If the latter are working while the former are not, most likely the issue pertains to your Bibutils install.

You can check that the Bibutils path was correctly configured by viewing the contents of the depends table. The depends_path for the bibutils record should not be NULL as seen below:

mysql> SELECT * FROM depends;

+------------+------------------+-----------------+--------------+
| depends_id | depends_external | depends_enabled | depends_path |
+------------+------------------+-----------------+--------------+
|          1 | refbase          | true            | NULL         |
|          2 | bibutils         | true            | NULL         |
+------------+------------------+-----------------+--------------+

In addition, please note that:

• the path to the Bibutils programs given in table depends must end with a slash
• permissions must be set correctly so that the Bibutils programs can be executed by Apache/PHP
• if safe_mode is set to On in your active php.ini file, then you'll need to put the Bibutils programs within the directory that's specified in safe_mode_exec_dir
• the PHP temp/session directory must be accessible & writable by Apache/PHP/Bibutils
• if you're on a hosted service, your Internet Service Provider may have given you a specific temp directory path which you may need to set explicitly in variable $sessionTempDir in file initialize/ini.inc.php

Some exports fail in refbase-0.8.0 on some win32 servers

Some WAMP stacks fail to execute Bibutils. A workaround is to upgrade to refbase-0.9.0 or greater.

Upload of files results in error message

If you're using refbase-0.9.0 and you're getting following error message when adding (or editing) a record that includes a file for upload:

Warning: preg_replace() [function.preg-replace]: Unknown modifier '\' in
.../refbase-0.9.0/includes/include.inc.php on line 3631

Warning: preg_replace() [function.preg-replace]: Unknown modifier '\' in
.../refbase-0.9.0/includes/include.inc.php on line 3634

then you may want to upgrade to refbase-0.9.5 or greater. Alternatively, you can apply a simple patch manually:

Please open file modify.php in your refbase root directory, goto line 1100 and replace this code:

$dirNamingScheme = trimTextPattern($dirNamingScheme, "[/\\]+", true, true);

with this:

$dirNamingScheme = trimTextPattern($dirNamingScheme, "[\/\\\\]+", true, true);

Import of records results in an error message

If you're trying to import records into your refbase database and you're getting an error message such as this one:

There were validation errors regarding the data you entered

then you might want check whether your record format is supported by refbase and whether its syntax is correct. Please see our import page for more information and links to example records for all supported formats.

If you're sure that your record format is supported but you still get an error message, please try to import your records at one of our demo databases. If this throws up the same error message, then refbase probably has problems recognizing your record format. In that case, we'd appreciate if you'd send us your problematic records so that we can look into the problem.

If, however, your records import fine in our demo database, then this hints at a problem with your local refbase installation. Note that import of records in BibTeX, Copac, Endnote (tagged text or XML), PubMed XML, SciFinder or MODS XML format requires Bibutils being installed on your server. If you think that you've correctly installed Bibutils on your server and still can't get import of the above mentioned formats to work, please let us know and we'll try to help.

Undefined iconv() despite --with-iconv

This problem was experienced on a FreeBSD web host, and has also been reported as a FreeBSD issue in the user comments at php.net, which suggests the resolution (which worked for me) to add the following block of code to the application before iconv() is called:

if (!function_exists('iconv') && function_exists('libiconv')) {
   function iconv($input_encoding, $output_encoding, $string) {
       return libiconv($input_encoding, $output_encoding, $string);
   }
}

Problems with special characters

See below for some troubleshooting guidance if you have problems getting higher ASCII characters (such as accented characters or umlauts) displayed correctly in refbase, or if you cannot correctly enter or search for higher ASCII chars in the refbase web interface. Encoding problems can be really tricky since many factors interact with each other, and encoding settings can differ greatly among different systems and versions.

Server settings

First of all, you should make sure that your MySQL server's character set and collation settings are setup correctly and consistently. For more information and instructions, please see parts 'a)' and 'b)' in section MySQL migration and character set problems.

If you'd like to use refbase with UTF-8 encoding, then you'll need MySQL version 4.1.x or greater. However, in our experience, MySQL 4.1.x seems to have problems with some Unicode characters, so if possible you should use refbase in conjunction with MySQL 5.x.

It might be also worth checking your web server's configuration file (e.g., in case of the Apache web server: httpd.conf or apache2.conf). On Ubuntu, for example, some users managed to cure their encoding issues by (un)commenting (or altering) following config setting in Apache 2:

AddDefaultCharset ISO-8859-1

Settings in refbase

When installing refbase via install.php, make sure that you've chosen the desired default character set (latin1 or utf8). Be aware that if you've tried to install refbase multiple times using the same MySQL database name (in initialize/db.inc.php) but with different settings as default character set, you must drop (i.e. delete) the database before installing it again with a different character encoding.

You can check the encoding of your MySQL database by issuing following command from within your MySQL command line interpreter:

SHOW CREATE DATABASE DATABASE_NAME;

In the above command, replace DATABASE_NAME with the actual name of your refbase MySQL database.

If you've chosen "utf8" upon installation, then you have to make sure that variable $contentTypeCharset in file initialize/ini.inc.php is set to "UTF-8". And if you're using higher ASCII chars in any variable values in file ini.inc.php, you should also re-save that file with encoding "Unicode (UTF-8, no BOM)".

If you've set variable $contentTypeCharset to "UTF-8", you could now access refbase in your web browser and verify that the head of the HTML source states the correct encoding:

<meta http-equiv="content-type" content="text/html; charset=UTF-8">

In case of a latin1-based refbase installation, the contents of the charset attribute should read "ISO-8859-1".

In order to test if refbase has been setup correctly, you should now add or edit a record via the refbase web interface and enter some special characters (such as áéíàèì or åæøöäü etc). Then, checkout again the added/edited record and verify that your entered characters display correctly. In addition, use refbase to search for these special characters and verify that your added/edited record is listed among the search results.

So, in summary, if you can 1) successfully enter special characters in refbase, 2) have them displayed correctly after saving your edits and 3) successfully search for these newly entered characters, then refbase has been set up correctly. However, if one of these actions (enter/display/search) does not work as expected, then you've still got problems.

Browser settings

If you're still experiencing problems, it's always a very good idea to try out another browser (or another browser on another platform). Also, try to manually set the encoding of your browser page to either "Unicode (UTF-8)" or "Western (ISO-8859-1)". In Firefox, this can be done via the "View > Character Encoding" menu. After you've set the encoding explicitly, please see if you can now enter/display/search for higher ASCII chars successfully.

Speaking of browser settings, you can often set a default character encoding within the browser's preferences which might be also worth checking out.

Import and file encodings

Finally, note that when importing data into refbase, you have to make sure that the character encoding of your bibliographic data file matches the character encoding of your refbase database. If this is causing you any trouble, copying and pasting the data into the refbase import form may actually work better. With regard to import, you should also ensure that you're using a recent version of Bibutils since some earlier versions of Bibutils had issues with character set support.

If you still can't get rid of your encoding issues, please let us know and we'll see what we can do.