Troubleshooting

This chapter provides some troubleshooting tips that you may find helpful when using the JBoss Application Server. Topics include:

For more information For complete information on configuring and managing the server, see The JBoss 4 Application Server Guide.

Startup issues

Binding to a network address

When running JBoss on Linux under the all configuration, which provides clustering, you must start JBoss with an explicit bind to a network address (using the -b parameter with run.sh). Make sure you have one of the following for that address:

An entry of IP/machine-name in /etc/hosts
An entry in DNS

This is particularly important if you run JBoss on a multi-homed server (a server that has multiple NICs). Without the -b parameter, JBoss will throw exceptions saying that the server could not bind to a given address.

Deployment issues

DeploymentException in exteNd Director Designer

If you are deploying an EAR from the exteNd Director Designer to JBoss, a timing issue between the Designer and JBoss may cause the following DeploymentException to display:

  No META-INF/application.xml found

This exception occurs on the first deployment, but that deployment should succeed anyway. You should not see the exception on subsequent deployments. (PPR 48905)

Classloading issues

About classloading

Unlike the exteNd Application Server, JBoss uses a flat classloading model. All classes are loaded by the same classloader.

However, if applications can't share classes because of version conflicts, you need to scope the classes from other deployments. Common indications of this are ClassCastException, IllegalAccessErrors, VerifyErrors and, in general, strange behavior that changes as new deployments are added or removed.

The two levels of scoping are:

Isolation from other deployments (which corresponds to how the exteNd Application Server works)
Isolation with override of server classes

WAR classloading is delegated to the web container (by default, Tomcat) and the web container's classloading rules apply (see the Tomcat documentation for details). But JBoss passes its classloader to the web server as context classloader, and the web container may use this context classloader.

JBoss also uses a trick to avoid classloader locks on server startup.

Scoping classloaders

For jboss-app.xml (JBoss EAR descriptor) and jboss.xml (JBoss EJB descriptor), add the following descriptor fragment constructs to enable scoped classloading with the deployment classes isolated from other deployments:

  <loader-repository>
     unique-scope-name:loader=unique-archive-name
  </loader-repository>

For jboss-web.xml (JBoss WAR descriptor), the following template applies:

  <class-loading>
     <loader-repository>
        unique-scope-name:loader=unique-archive-name
     </loader-repository>
  </class-loading>

For more information, see the JBoss Wiki page on classloading configuration.

Classloader debugging

Classloader logging is no different than any other JBoss logging, which is based on log4j. To enable logging for classloaders, edit log4j.xml (in server/xxx/conf) and add:

  <appender name="UCL" class="org.apache.log4j.FileAppender">
     <param name="File" value="${jboss.server.home.dir}/log/ucl.log"/>
     <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="[%r,%c{1},%t] %m%n"/>
     </layout>
  </appender>
  
  <category name="org.jboss.mx.loading" additivity="false">
     <priority value="TRACE" class="org.jboss.logging.XLevel"/>
     <appender-ref ref="UCL"/>
  </category>

Note that element log4j:configuration must match:

  (renderer*,appender*,(category|logger)*,root?,categoryFactory?)

The order of tags is important.

Database issues

Database connection recovery

If an action on a connection in the pool fails, the server will check all connections in the pool and recreate them if necessary.

JBoss can test a connection before handing it out by calling a SQL statement. Add the following element to the -ds.xml file:

  <check-valid-connection-sql>some cheap sql statement</check-valid-connection-sql>

Datasource statistics

In the JBoss JMX Console, you can view statistics on a specific datasource (such as MyDatasource) by going to the jboss.jca section and clicking:

  name=MyDatasource,service=ManagedConnectionPool

Clustering issues

Editing the JGroups configuration

When running JBoss on Windows with clustering (under the all configuration), you must edit the JGroups configuration for the following files in the deploy directory:

cluster-service.xml
tc5-cluster-service.xml

Look for this comment and follow the instructions:

  <!-- UDP: On Windows machines, because of the media sense feature
       being broken with multicast (even after disabling media sense)
       set the loopback attribute to true -->