This page describes how to use a Java-level debugger to debug Cocoon itself. For notes on debugging Cocoon-based applications, see also: DebuggingWithViews, DebuggingXMLandXSLTransformation, and Cocoon Profiler. However, Java-level debugging can be useful for tracing Cocoon-based applications as well.

On the Cocoon users mailing list Leszek Gawron wrote the original step by step guide to debug Cocoon using Eclipse or Swat. Now here's the wikified version.

Debugging Cocoon requires two steps:

  1. Run Cocoon (in a servlet container) in a Java virtual machine (JVM) that has remote debugging enabled.
  2. Tell your Java debugger/IDE, such as JSwat or Eclipse, to connect to the JVM process.

1. Run Cocoon with remote debugging enabled

The easiest way to run Cocoon set up for remote debugging is to run


Note: If you prefer to use tomcat for remote debugging, run: $TOMCAT_HOME/bin/ jpda start

The default debug port set in the cocoon.bat or is port 8000.

The simplest way to test that your system is set up for remote debugging is to use jdb as described in step 2.

2. Connect your debugger/IDE to Cocoon JVM


jdb is not generally recommended as a debugging tool because its user interface is very primitive. However, you can use it as a simple test case to make sure that your Cocoon JVM is set up to accept remote debugging connections. The jdb executable is typically found in the same directory in your path as the java executable. Type

jdb -attach localhost:8000

(for un*x/linux) or

jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=8000

(for Windows).A successful connection is indicated by

Set uncaught java.lang.Throwable
Set deferred uncaught java.lang.Throwable
Initializing jdb ...

The error shmemBase_attach failed: The system cannot find the file specified will occur if you are on Windows and try to use jdb -attach localhost:8000; this will try to use shmem by default instead of sockets. The error Connection refused: connect on Windows may indicate that the Windows Firewall is blocking the connection (it may not notify you of the blockage, even if configured to do so). Go to Control Panel / Windows Firewall / Exceptions / Add Port, and set Name = remote debugging, Port = 8000, TCP.

JSwat 2.3

Everything works quite fine but jSwat functionality is not enough for us. So lets switch to:


This procedure works in IntelliJ IDEA as well. Verified Nov 2004 by MicahDubinko

For XSP debugging you need additional steps:


You have to have all source files to be placed relatively from your project home.
This change needs a servlet container restart.

DebuggingCocoon (last edited 2009-09-20 23:40:33 by localhost)