7. Troubleshooting

Below are a number of common issues encountered while building and starting up Sakai, but you may also benefit from the expert opinions that reside on the sakai-dev list. To join, visit collab.sakaiproject.org, create a new account, log in to your My Workspace, and then use the Membership tool to join the group named DG: Development. Then you can begin to send emails to (and receive them from) sakai-dev@collab.sakaiproject.org. To later unsubscribe, you can simply use the same Membership tool to unjoin the site.

7.1. Build Issues

7.1.1. JAR download failures

A first build of Maven on a fresh installation may warn of numerous jar download failures if you include the clean phase. This is a nuisance, but not otherwise a problem. Even when doing a clean maven tries to download all dependencies, including those Sakai jars that may not be built until the later build phase. Once they are built and placed into the repository, maven is perfectly happy for the next "clean build" cycle. The upshot is that you may see these errors for your first build, but you shouldn't see them for subsequent builds. It also means that you're better off not including the clean phase during your first build of a new version of the code.

If this does not account for the download failures you're seeing, then you may want to double-check your maven.remote.repo setting. See the Maven Configuration section, and follow it precisely.

7.1.2. Out of Memory errors

You may find that your machine runs out of memory while it is building Sakai. As it turns out, maven does not read JAVA_OPTS when it starts up, and so if your build output complains of "Out of Memory" errors you'll need to set an additional environment variable, namely, MAVEN_OPTS. The value in the sample Unix command below should be more than enough:

export MAVEN_OPTS="-Xmx384m -XX:PermSize=48m"

7.1.3. Uninformative failure messages

If you need more detailed output to track down a build error, maven can be run in debug mode by adding the -x argument, e.g. maven -x.

7.1.4. Building only a single module

If you'd like to have the Sakai build targets and goals available for building only a single module (i.e. instead of rebuilding the entire source tree again to accomplish this), then you'll want to have the maven plugin for Sakai installed. 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:download -DgroupId=sakaiproject -DartifactId=sakai -Dversion=2.2

Note that the version you should use in the above command is the one found as the value of the sakai.plugin.version property in the sakai/master/project.properties file. It is not necessarily (and in fact often isn't) the same as the version of Sakai you're using.

7.2. Tomcat Startup Issues

7.2.1. Finding the Tomcat logs

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

Changing the 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 sakai-src/kernel/log-configure/src/conf/log4j.properties, and the relevant property is:


To turn on debug logging for all of Sakai, change that value from INFO to DEBUG. In order to turn on debug logging for just a single component of Sakai, add a line such as in the following example, which will leave most of Sakai at INFO, but generate DEBUG level messages for the SQL service:


The logging controls are part of the new LogConfigurationManager, implemented as a component, the Log4jConfigurationManager, in the util module. It can be disabled, if we really don't want it to do anything, with an entry in sakai.properties:

enabled@org.sakaiproject.log.api.LogConfigurationManager = false

Logging levels are first established in the log4j configuration file we deploy from Sakai. The source for this file is in: sakai/util/util-impl/log/src/conf/log4j.properties. This is made into a jar and deployed to common (this is a requirement of log4j configuration in Tomcat). We can set logging levels in this file. For example:

# Application logging options

# Ignore erroneous MyFaces variable resolver warnings

This sets any logger with "org.sakaiproject.*" to INFO level, and the "org.apache.myfaces.el.VariableResolverImpl" to ERROR level. The problem with this approach, however, is that it requires a change to the source, and a redeploy. Hardly convenient.

Happily, logging levels can now also be specified in sakai.properties. This augments and overrides the levels set in the default config file. Example:

log.config.1 = ALL.org.sakaiproject.log.impl
log.config.2 = OFF.org.sakaiproject
log.config.3 = DEBUG.org.sakaiproject.db.impl

This uses the established (but awkward) method of having a name.count followed by name.1, name,2, etc. to form an array of strings for the value "name". In this case, the name is "log.config". The values are of the form LEVEL.logger, and the possible levels are: OFF TRACE DEBUG INFO WARN ERROR FATAL ALL.

As you can see, Sakai uses log4j for logging. See the official log4j documentation for more information about how to configure it if you have questions.

For Mac and *nix systems, the most important log is found in logs/catalina.out of Tomcat. It can be instructive to watch this log as Tomcat is starting up, by using a startup command like the following:

bin/startup.sh; tail -f logs/catalina.out

Tomcat on Windows tends to be a little more puzzling about its logs, and it includes more of them, but its default behavior is to open catalina.out in a new window as soon as you start Tomcat. If you need more information about the logs in Windows, we'll refer you to the official Tomcat documentation.

Other Logs

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

7.2.2. "Unsupported major.minor version 49.0"

If this message appears in catalina.out during startup, it means that you've built Sakai for Java 1.5, but your JRE is 1.4. Go back to the Set up Build Environment section and double-check your Java version and environment variables.

7.2.3. "java.net.BindException: Address already in use"

If this message appears in catalina.out during startup, it means that some other application is already running on the port you've assigned for this Tomcat instance. It's most likely another Tomcat. It may be that you didn't stop Tomcat from a previous run, or you may already have Tomcat running on that machine.

If you need to run more than one Tomcat on the same machine, see Tomcat documentation for instructions on how to configure to run Tomcat on a different port.