Contribute to the DSpace Development Fund

The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.

Table of Contents:

Error Log Files

  • DSpace log: [dspace]/log/dspace.log (usually)
    • [dspace] is the location where DSpace is installed.
  • Tomcat log directory: [tomcat]/logs (usually)
    • [tomcat] is the location where Tomcat is installed.

Resources

General Instructions

DSpace 7.x or later

Finding the detailed error message is important!

In DSpace 7.x or 8.x, there are two main places where detailed error messages may be found. It is important to locate these detailed error messages in order to debug any issues you are seeing. (The generic error messages that appear in the User Interface do not provide enough information to debug the problem.)

  1. In your web browser's DevTools when running the User Interface - because the v7 User Interface is built with JavaScript (Angular.io), some errors are only visible in your browser (and therefore will never appear in log files). See "Finding the Error Message in the User Interface" below.
  2. In the backend's log files - Some errors (especially 500 responses/errors) will result in the error message being logged to your dspace.log or Tomcat logs. See "Finding error messages in the REST API logs" below.

Once you locate the detailed error, see the section on "Report the Error and Describe How You Encountered It" below.

1. Finding the Error Message (or odd behavior) in the User Interface (Try this first!)

The User Interface is built with JavaScript (Angular.io). This means that some errors are only visible in your browser (and therefore will never appear in log files).

To find the errors in your browser, you will want to open your browser's Developer Tools and then try to reproduce the error again.

  1. Open up your browser's "Developer Tools" window/tab.
    1. In Chrome, go to "More Tools → Developer Tools". 
    2. In Firefox, go to "Web Developer → Web Developer Tools".
    3. In Microsoft Edge, go to "More Tools → Developer Tools".
  2. With the "Developer Tools" open, try to reproduce the error or odd behavior on your DSpace site.
  3. As you perform activities in your DSpace site, you will see many requests listed in the "Network" tab of your "Developer Tools" window
    1. Successful requests will appear in black text, and have a "200" (or 2xx) status listed next to them.
    2. Errors will appear highlighted in red.  They will have a 4xx or 5xx status listed next to them. Some common HTTP status codes & their meaning in DSpace include:
      1. 400 Bad Request - The User Interface sent an invalid request to the DSpace backend.  This may be the sign of a bug in the User Interface.
      2. 401 Unauthorized - The request was rejected by the DSpace backend because the user is not authenticated.
      3. 403 Forbidden - The request was rejected by the DSpace backend because the authenticated user doesn't have the access rights necessary to make that request.  
      4. 404 Not Found - The requested content wasn't found by the DSpace backend.  NOTE: In some situations, a 404 response may be expected behavior. For example, if Google Analytics is disabled, then the request for the "google.analytics.key" will return a 404 Not Found. This tells the User Interface that this feature has been disabled.
      5. 500 Internal Server Error - The DSpace backend did not respond to the User Interface in the expected manner.  This may be a sign that an error occurred on the backend. Check your DSpace logs or Tomcat logs as described below in the section on "Finding error messages in the REST API logs". 
    3. Clicking on an individual request will show you the exact Headers sent/returned and the error Response.  This may provide more information about the error itself, and why it occurred.
  4. When errors occur, you will also see an error stacktrace in the "Console" tab of your "Developer Tools" window.  This may provide additional information about the error
  5. If no errors are shown in your "Developer Tools" window, you should also look for the following on the "Network" tab:
    1. When you reproduce the issue, are you seeing one request that is hanging or taking many seconds to respond?  If so, please capture information about the exact request that is slow (click on the request & look at the Headers tab).  Also, check to see if the REST API is logging errors related to this request.  This is a sign of a possible REST API bug or performance issue.
    2. When you reproduce the issue, are you seeing a very long or never-ending stream of requests?  If so, please capture information about any requests which may be repeating.  This is a sign of a possible User Interface performance issue.


If you have just installed or upgraded DSpace recently, make sure you are aware of the "Common Installation Issues" section at the bottom of the "Installing DSpace" guide.  This section provides hints/tips for solving errors that may occur because of misconfiguration.


2. Finding error messages in the REST API logs

Some (but not necessarily all) errors will result in logged errors on the backend. Similar to DSpace 6.x and below, the error message should be in either [dspace]/log/dspace.log OR [tomcat]/logs/.

Usually, the culprit error will appear in the logs with a line similar to one of the following:

  • yyyy-mm-dd time ERROR ... OR,
  • yyyy-mm-dd time WARN ...

3. Debug mode for the REST API (if necessary)

If you are not seeing the error appear in the REST API logs, and the error information is minimal in the User Interface, you can tell the REST API to always return the entire error stacktrace in any error response.  This is done by temporarily adding the following to your local.cfg (on the backend): 

# This tells the REST API to include a "stacktrace" param in error responses
# This param will include the full Java stacktrace of the error
server.error.include-stacktrace = always

Enabling this setting requires you to reboot your servlet engine (e.g. Tomcat). 

Once this setting is enabled, you can reproduce the error from the User Interface. Now, the error message in your User Interface (in your browser's Developer Tools) may show the entire Java stacktrace that resulted in the error.

WARNING: Keep in mind that you should only enable this setting TEMPORARILY.  Keeping this set to "always" is a security issue in Production scenarios, as it allows anyone to view the detailed stacktrace of any error they cause.  These stacktraces can sometimes leak important information about your underlying system which can help hackers to find vulnerabilities.

4. Turning on Debug Logging for the REST API (if necessary)

If none of the above helped, or you are hitting a very strange backend error, you can change the DSpace logger settings to DEBUG which will sometimes provide you with more information about the error. To turn on debugging, visit the [dspace]/config/log4j2.xml file and do the following:

  • To enable DEBUG logging in the dspace.log file, change the loglevel.dspace Property to DEBUG rather than INFO.

  • NOTE: You'll need to restart Tomcat after enabling DEBUG mode in the log4j2.xml file.

  • WARNING: Make sure to turn off debugging once you are finished. Leaving debugging turned on will cause the log files to grow very large very quickly!

5. Found an error message! Now what?

See "Report the Error and Describe How You Encountered It" section immediately after this.

Report the Error and Describe How You Encountered It

Before reporting the error

Before reporting any issue, it's best to check and see if the answer is already easily available.

If neither of these resulted in a solution to your error, proceed to "Reporting the error" below.

Reporting the error

Your error report should include the following information:

  1. Your environment: Version of DSpace (most important), operating system, version of Tomcat, Java, Node, etc.
    1. NOTE: On the backend, simply running "./dspace version" from the command line will provide much of this information for you.
  2. The exact steps you took to encounter the error and/or the page where this error occurs. Often, we need to understand how to replicate the error before we can determine what the underlying cause is.

  3. The error stacktrace / message that you found in your log file or Browser's "Developer Tools" window.  

There are a few ways you may choose to report this error. However, we ask that you only choose one, depending on which you prefer.

DSpace 6.x or earlier

Finding the Error Message in your Log Files

  1. If the expected information simply never appears, leaving a blank browser screen, the problem is likely with either a servlet (for JSPUI) or an XSLT Theme (for XMLUI). The error message should be in either [dspace]/log/dspace.log OR [tomcat]/logs/.
    • For the XMLUI, you may also want to check the Cocoon logs to see if any extra information can be found there. Cocoon logs can be found in these locations: 
      • DSpace 1.5.1 or previous: [tomcat]/webapps/<name-of-webapp>/WEB-INF/logs/
      • DSpace 1.5.2 or later: [dspace]/log/cocoon.log
  2. If you get an "Internal Server Error" message, you will have to check the log files for a full error listing. If your email address is set up in dspace.cfg (alert.recipient) as the DSpace Administrator, you should receive an email with this full error listing. If not, move into the DSpace log directory ([dspace]/log) and view the end of the log file:
    • (Linux or Mac OSX) Go to the DSpace log directory via the command line and enter: tail -100 dspace.log Alternatively, you can open up the dspace.log file in your favorite text editor and look near the bottom of the file for the error message.
    • (Windows) Go to the DSpace log directory, and open dspace.log in your favorite text editor. Look near the bottom for the error message.
  3. Usually, the culprit error is in the first five to ten lines of the error stack listing. The error stack starts with a line similar to one of the following:
    • yyyy-mm-dd time ERROR ... OR,
    • yyyy-mm-dd time WARN ...

Searching for Fixes to Common Errors

See "Report the Error and Describe How You Encountered It" section immediately above for details.

Turning on Debugging (optional)

  • If you'd like to try and do some debugging yourself, you can change the DSpace logger settings to DEBUG which will sometimes provide you with more information about the error. To turn on debugging, visit the [dspace]/config/log4j.properties file and do the following:

    • To enable DEBUG logging in the dspace.log file, change the log4j.rootCategory and log4j.logger.org.dspace settings to DEBUG rather than INFO.

    • (XMLUI Only) To enable DEBUG logging in the cocoon.log file, change the log4j.logger.org.apache.cocoon setting to DEBUG rather than INFO.

    • NOTE: You'll need to restart Tomcat after enabling DEBUG mode in the log4j.properties file.

    • WARNING: Make sure to turn off debugging once you are finished. Leaving debugging turned on will cause the log files to grow very large very quickly!

  • Depending on where you got your Java runtime environment, you may have the jps command.  jps -v can show you the options actually used to run your Servlet container, which can be useful in debugging startup issues.  A plain jps command will list process IDs of running JREs, which you can use with your favorite process monitoring tools.  jps can only show processes which your user account is allowed to inspect, so you should run it as the user which runs the container, or as a superuser.

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.