Table of Contents
When VuFind doesn't behave as expected, there are several things you can do to gain more information about what is going wrong.
Check Error Logs
If you are not seeing on-screen errors, it is possible that they are being captured by the Apache error log (often found in /var/log/apache2/error.log, /var/log/httpd/error.log, or a similar path). Checking the end of this log (or watching it with the “tail -f” command) may reveal useful information.
If you cannot find your Apache error logs, you should check whether any <VirtualHost> definitions in your Apache configuration are sending logs to a non-standard location using the ErrorLog directive.
Some operating systems use PHP-FPM to run PHP, and the PHP-FPM error log is another place to check in this case. It is often found at /var/log/php-fpm/www-error.log (or something similar).
Turn on Development Mode
VuFind's Apache configuration includes an environment variable called VUFIND_ENV which tells the software what kind of environment it is running in – development or production. By default, this is set to production, which activates performance-oriented caching and disabled detailed error messages for greater security. If you switch this setting to development mode (by editing $VUFIND_LOCAL_DIR/httpd-vufind.conf, uncommenting the appropriate VUFIND_ENV line, and restarting Apache), most cache-related problems will automatically go away, and all on-screen error messages will be presented in much greater detail for debugging purposes.
Clear the Cache
When in doubt, empty the contents of $VUFIND_LOCAL_DIR/cache – this can solve several common problems, such as changes to language files not appearing immediately.
Check Permission / Security Settings
If Apache is not allowed to read or write certain directories (particularly the cache), VuFind may have problems. The $VUFIND_LOCAL_DIR/cache directory (and all of its subdirectories except “cli”) should be writable by the user running Apache (often named www-data or apache, depending on your operating system). The $VUFIND_LOCAL_DIR/cache/cli directory (and all of its subdirectories) should be writable by the user running command-line utilities. Also make sure that SELinux is not interfering with VuFind's operations; see the Fedora Installation Instructions for more details on SELinux.
If you are not sure which user is allowed to write to the cache, try running “chmod -R 777 $VUFIND_LOCAL_DIR/cache” to make the cache world-writable. After accessing VuFind, you can then “ls -l $VUFIND_LOCAL_DIR/cache/” and see which user owns the files. You can then run: “sudo rm -rf $VUFIND_LOCAL_DIR/cache/* ; sudo chmod 775 $VUFIND_LOCAL_DIR/cache ; chown user:user $VUFIND_LOCAL_DIR/cache” (replacing user:user with the appropriate user/group) to make your cache settings secure again.
Turn on Debug Mode
If you want more information about what VuFind is doing, you can set the debug setting in the [System] section of your config.ini file (generally found in $VUFIND_LOCAL_DIR/config/vufind/config.ini) to true. This will output debug messages as part of the HTML that VuFind generates. In many cases, these will reveal useful information, but be warned: in some cases, the debug messages will be difficult to read, and they may interfere with some of VuFind's AJAX functionality. If you encounter those problems, proceed to the next section….
"Debug on the Fly"
You can also turn on debug mode via a URL parameter, if you have appropriate permissions set up. If you add a “debug=true” parameter to the end of any VuFind URL (using an appropriate ? or & separator, of course), debug mode will be activated if the current user has the “access.DebugMode” permission granted via the permission system. This feature was broken in several VuFind releases; see VUFIND-1382 for details on affected versions and a fix for the problem.
Turn on Logging
If quick on-screen debugging causes problems or does not meet your needs, you can also activate VuFind's logger, controlled by the [Logging] section of config.ini. This will allow you to control the type of messages that are logged, the level of detail in which they are described, and their destination: log file, database table, email address, etc. Comments in the configuration file describe the options in more detail.
Logging is not only a useful way to troubleshoot a known problem, but it is also a good way to detect unknown problems – setting up a log in a production system and monitoring it for unusual activity is strongly recommended.
In a situation where you need to closely inspect how code is behaving, you can use PHP's Xdebug extension for full code-level debugging functionality – step through code, inspect variable values, etc. Several IDEs support Xdebug, and a Google search for “Xdebug” and the tool of your choice should provide the latest instructions on how to set things up. If you are not already using an IDE, see our Recommended Tools page for some free, open source options.
Use Your Browser's Debugging Tools
See the ILS Driver Troubleshooting page for some more details on using the console (as well as tips on resolving problems specifically related to communication between VuFind and your Integrated Library System).
When you have logging or debug mode enabled, you may find an error that has a known solution. See the Common Issues page for more information.