Differences

This shows you the differences between two versions of the page.

--- development:troubleshooting [2019/02/27 13:55] – demiankatz
+++ development:troubleshooting [2024/02/23 11:36] (current) – [Further Reading] demiankatz
@@ Line 1: / Line 1: @@
 ====== Troubleshooting ======
-When VuFind doesn't behave as expected, there are several things you can do to gain more information about what is going wrong.
+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), cache-related problems will automatically go away, and all on-screen error messages will be presented in much greater detail for debugging purposes.
+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....
+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.
+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.
@@ Line 25: / Line 47: @@
 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).
+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 =====
+These pages contain more specialized troubleshooting topics:
+  * [[configuration:ils:troubleshooting|ILS Driver Troubleshooting]]
+  * [[indexing:solrmarc:troubleshooting|SolrMarc Troubleshooting]]
 ---- struct data ----
+properties.Page Owner :
 ----