As of version 5.5.5, CycleServer supports debugging Python plugins against a running CycleServer instance. It uses Pydev, which can work in Eclipse (tested) or in pyCharm (not tested). It is currently limited to debugging one component at a time, since each component corresponds to a separate Python interpreter.

Debugging Unit Tests

To setup debugging for Python plugins, do the following:

  • Configure PyDev
  • Go to Preferences – PyDev – Run/Debug and increase the connect timeout for debugger to 60000
  • Add breakpoints within Eclipse

Debugging Python-Based Unit Tests

You can run and debug Python-based unit tests with PyDev. To do this:

  • Right click on the test file
  • Select Run As
  • Select either Jython Run or Jython unit-test. If you select Jython unit-test, you can add breakpoints to the source and step through code.


Make sure that the project is building correctly (without an exclamation point on the project name), or you may get errors running unit tests with PyDev. To do this, run gradle eclipse from the command line and refresh the project in Eclipse.

Debugging a live CycleServer Install

It is possible to set breakpoints in Eclipse and access them within a running CycleServer. Note that this method tests the deployed version of your component. If you want to make changes and test them, you must run gradle
and then run gradle pydebug again.

  • Ensure your local CycleServer is running
  • Ensure eclipse’s Debug server is running. Switch to the Debug view and select PyDev | Start Debug Server. This will listen on port 5678 for Python processes to connect to. You may need to switch to the “Debug” View to find this option.
  • cd to your component directory
  • run gradle pydebug
  • execute gradle deploy if you have made any changes to your component that you wish to be active in CycleServer
  • Add breakpoints liberally within eclipse
  • Interact with CycleServer via the REST API, web interface, or command-line interface to trigger the
    code path you wish to debug

When your breakpoints are reached, Eclipse should automatically open the Debug view.

gradle pydebug should give you the following output:


Starting PyDev debugging session...
Debugger active. Press Ctrl-C to end debugging...
> Building 0% > :pydebug

This will make CycleServer connect to the debugger and you can set breakpoints and step through code. Press Ctrl-C when done debugging to resume normal mode. You can also end the Debug Server in Eclipse.

Debugging Debugging

Note that you cannot access breakpoints placed in arbitrary locations when debugging unit tests. For example, when testing a ReST API endpoint, any breakpoints in the code handling the API endpoint will not be exercised. This is because the code handling the HTTP requests runs in a private Java thread that is not configured for Python debugging. That said, you can hit any breakpoint when debugging a live CS instance.

If you get an error with the message “Timed out after 20.0 seconds waiting for Python script to connect” this means you need to increase the Debugger timeout.


This is still a preview feature so it may have issues. It should be possible to connect, debug, redeploy the component, then connect again to test the new version, but some changes may not be reflected in the new debugging session. Also, code may continue to execute slower even after exiting the debugger, if the settrace hooks aren’t cleared properly in Jython.

Debugging Java Code

To enable remote Java debugging in CycleServer, add the following to your webServerJvmOptions setting in your config/ file inside the CycleServer installation directory:

-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

To attach Eclipse to CycleServer, create a new “Remote Java Application” launcher via the Run | Debug Configuration dialog, and specify localhost and the port (eg 8000).Then launch that configuration to debug a running instance.

You can set the above settings permanently, even if you are not debugging. This will let you attach at any time.

If you want to debug an issue early in startup, change to suspend=y. The application will be paused until you connect the debugger.


With suspend=y set, CycleServer will hang on startup until you attach a debugger to it!