VuFind Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Troubleshooting ======

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 [[https://php-fpm.org/|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 [[installation:fedora|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 [[configuration:permission_options|permission system]]. This feature was broken in several VuFind releases; see [[https://vufind.org/jira/browse/VUFIND-1382|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.

===== Use Xdebug =====

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 [[development:recommended_tools|Recommended Tools]] page for some free, open source options.

===== Use Your Browser's Debugging Tools =====

The above options are helpful when a problem is occurring in pages visible to the end user, but sometimes there is a Javascript problem, or an issue related to code that is generating an AJAX response. In those cases, looking for errors in your browser's debugging console and/or monitoring network communications may help narrow down the problem.

See the [[configuration:ils:troubleshooting|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).

===== Common Issues =====

When you have logging or debug mode enabled, you may find an error that has a known solution. See the [[development:troubleshooting:common_issues|Common Issues]] page for more information.

===== Further Reading =====

This page contains more specialized troubleshooting advice based on the connection to your ILS:

  * [[configuration:ils:troubleshooting|ILS Driver Troubleshooting]]