Troubleshooting Guide

This guide is still in its infancy, focusing on a handful of the most common issues that plague novice deployers of Sakai, and a couple of the basic methods used to diagnose problems and delve more deeply into understanding the software.

Table of Contents

    Maven errors
  1. jar download failures
  2. Tomcat write permissions
  3. Beta versions of Maven
    Tomcat Logs
  1. Log overview
  2. Finding the logs
  3. Watching  logs at startup
  4. Log configuration
  5. Other Logs
    Remote Debugging with Eclipse

Maven Errors

*NOTE: See the maven.pdf resource posted to the Resources area of the sakai-dev site on for a more thorough examination of how maven is used with Sakai

  1. jar download failures

    A first build of Maven on a fresh installation will warn of numerous jar download failures during the clean phase. This is not a problem. Even when doing a clean, maven tries to download dependencies. When the repository is initially empty maven can freak out during the clean phase while looking for jars that the impending build phase has yet to build. Once they are built, maven clean is perfectly happy next "clean build" cycle.

  2. Tomcat write permissions

    The most common maven build failures stem from the user running maven not having write access to the Tomcat directories being deployed to. Maven's error messages should make this fairly plain when it happens, and will even specify which copy or delete operation failed.

  3. Beta versions of Maven

    Problems have been reported using some of the latest beta versions of maven (currently 1-1-beta). Maven 1.0.2 has been working reliably with Sakai for over a year, and we recommend it over any new, non-stable versions.

Tomcat Logs

  1. Log overview

    Once you have Sakai installed, configured and started, you can monitor Sakai by watching the logs. The log level for the standard Sakai source code and the demo is set to show info and warnings only. If you need to see more information, you can change the logging level to enable debug messages as well for all of Sakai or merely specific components. Sakai uses log4j for logging: see the log4j documentation for more information about how to configure it. Watch for the WARN: messages. There are going to be some "normal" ones at startup, and some will likely slip by at runtime, but any warning is potentially something you might want to check out.

  2. Finding the Logs

    On Mac and *nix systems the most important log is catalina.out in $CATALINA_HOME/logs.

    On Windows systems the situation is a little more complicated. The logs are also stored in $CATALINA_HOME\logs, but there are more of them:


    The Windows equivalent of catalina.out is the catalina.%date%.log, so focus on that one.

  3. Watching logs at startup

    Tomcat can take a long time to load the Sakai application, and it's often a good idea to watch the log in real-time as Tomcat comes up. You can watch for errors, and it will also allow you to be sure when Tomcat is done starting up. To do so on Mac or *nix systems you can run the command:

    tail -f $CATALINA_HOME/logs/catalina.out
  4. Log Configuration

    To change the logging for Sakai, you need to change Sakai source code and re-deploy sakai. The file you need to change is:


    The section that pertains to Sakai as distributed is:

    To turn on debug logging for all of Sakai, change that to:

    To turn on debugging only for one part of Sakai, add a line like the one below:

    This, for example, will leave most of Sakai at INFO, but the legacy SQL service will generate DEBUG level messages.

  5. Other logs

    The SMTP server logs from Sakai will be written to the $CATALINA_HOME/sakai/logs directory.

Remote Debugging with Eclipse

Here is a very brute force and time consuming method which has the benefit of being very "instructional." In a slow way.

Load Sakai into your Eclipse environment (get an Eclipse book if you need to), then start your Tomcat this way: jpda start

This configures the JVM to open a debugging port (8000) [Security warning: anyone can now access this Sakai instance using the following technique, so it's strongly suggested that you consider changing ports. Take a look at the script for more details.]

Then in Eclipse choose:

  1. Debug -> Remote java application -> New
  2. Give it a name
  3. In the Source tab select Add
  4. Select Java Project from the Add Source popup
  5. In the Project Selection popup select all the Sakai2 projects you created above
  6. Close all that, getting back to the Debug setup window
  7. Double-check that the connection type is appropriate. Socket attach should work.
  8. Double-check the host name and port.
  9. Then click the debug button...

Nothing immediately happens, but this is OK. Root around the code in Eclipse to find the RequestFilter over in the kernel project. Set a break point in the doFilter. Near the top will do.

Now access your site via a web browser. At this point you can have the pleasure of walking through the Sakai request using the Eclipse debugging tools.

Eclipse may well shudder a bit and ask if you would like to continue in the debugging perspective. You do. In this perspective you will see some arrows that point down (enter fcn call) and sort of loop over (skip entry, go to next stmt). Check that Eclipse book again if you've not used this part of Eclipse.

In practice you'll more often set these break points far far far further down the call stack; you'll see why after you grovel through this a few times.