When VuFind doesn't behave as expected, there are several things you can do to gain more information about what is going wrong.

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.

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.

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.

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….

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.

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 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).