Sakai Logo

6. Troubleshooting

6.1 Common Issues

Out of Memory Errors:
If the screen of a tool fails to load and catalina.out reports an "Out of Memory" error, then you'll likely need to alter your JVM settings. Many modern app-server technologies make use of objects that persist for longer periods of time, and therefore many Sakai deployments have found it beneficial to adjust the JVM with flags to specify enough permanent space to accommodate these objects. Programs that dynamically generate and load many classes (e.g. Hibernate, Struts, JSF, Spring etc.) usually need a larger permanent generation than the default 32MB maximum. The permanent generation is sized independently from the other generations because it's where the JVM allocates classes, methods, and other "reflection" objects. Specify flag -XX:PermSize=16m to allow the JVM to start with enough memory so that it doesn't have to pause apps to allocate more memory. Specify -XX:MaxPermSize for the size of the permanent generation to be greater than the default 32MB maximum. When running on servers with multiple cpus, you'd multiply the memory by the number of CPU's. For example, to run a quad-processor machine you'd set the flag to -XX:MaxPermSize=128m. See also the "JVM Tuning" discussion in the Post-Installation Configuration section.

6.2 Working with Maven

Maven in Sakai
See the maven.pdf posted to the Architecture Docs folder of the sakai-dev site's resources (link below) for a more thorough examination of how maven is used with Sakai. You can also find the "source" of this document as an MSWord file in subversion:
  • Newer versions of Maven:
    Sakai will fail to build with the latest beta versions of maven (currently 1-1-beta, and 2.0). Maven 1.0.2 has been working reliably with Sakai for over a year, and the Sakai plugins have not been altered to conform to the architecture of Maven 2, so that even if Maven 2 comes out of beta in the near future 1.0.2 should continue to be used.
  • Updating the plugin:
    You can install the Sakai plugin into your maven environment, which is useful for letting you run maven commands from the modules and projects within Sakai instead of always building the entire code base. Installing the plugin makes it available whenever you use maven, not just for those projects that declare a dependency on the plugin. You will need to do this once each time you upgrade a minor point version of sakai.
    Maven plugin install
    maven plugin:download -DgroupId=sakaiproject -DartifactId=sakai -Dversion=2.1
    Note that the plugin-version is not necessarily the same as the Sakai version. The correct version to use will be available as the value of the sakai.plugin.version property in the sakai/master/ file.
  • 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.
  • 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.
  • Maven -x:
    Running maven with the x argument runs it in debug mode, and produces even more verbose output, which can be very helpful if the standard output is not providing enough information about errors.

6.3 Tomcat Logs

  • 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.
  • 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:
    • jakarta_service_%date%.log
    • admin.%date%.log
    • catalina.%date%.log
    • host-manager.%date%.log
    • localhost.%date%.log
    • manager.%date%.log
    The Windows equivalent of catalina.out is the catalina.%date%.log, so focus on that one.
  • 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

    You can achieve something similar in Windows with Cygwin or other utilities.

  • 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.
  • Other logs
    The SMTP server logs from Sakai will be written to the $CATALINA_HOME/sakai/logs directory.