Warning: count(): Parameter must be an array or an object that implements Countable in /customers/2/8/1/bizzybee.be/httpd.www/wp-includes/post-template.php on line 251 Warning: count(): Parameter must be an array or an object that implements Countable in /customers/2/8/1/bizzybee.be/httpd.www/wp-includes/post-template.php on line 251 Warning: count(): Parameter must be an array or an object that implements Countable in /customers/2/8/1/bizzybee.be/httpd.www/wp-includes/post-template.php on line 251 Warning: count(): Parameter must be an array or an object that implements Countable in /customers/2/8/1/bizzybee.be/httpd.www/wp-includes/post-template.php on line 251

Debugging Java code in Domino Designer 8.5 or 9

Since Domino 8.5 it should be possible to debug your java agents directly in the Domino Designer IDE. In theory. It’s documented in the help, but it took me several hours (and more) to get it to work. This is how I use it, and some caveats I encountered.  I think my way of working is easier than how it is explained in Help, so follow these steps to locally debug a Java agent (“foreground debugging”)

Initial setup

  1. Add JavaEnableDebug=1 to the notes.ini file in the Notes directory.
  2. Choose Tools > Java Debugging Preferences.  Check Client Agents/Applets in the dialog and specify a port number  (default: 8701 may be just fine) to connect the debugger to the Notes client.
  3. Restart Notes.

Prepare the agent for debugging

  1. Open the Java agent in Domino Designer.
  2. On the Properties tab – Basics, select Compile Java code with debugging information.
  3. Open the main class, for example
  4. Go to the Debug Perspective (Window – Open Perspective – Other… – Debug).
  5. Create a debug configuration:
    1. Choose Run – Debug Configurations…
    2. Right-click Remote Java Application and choose New.
    3. Change portnumber to 8701 or whatever port you specified in step 2 of initial setup above, leave the rest as is.
    4. Choose Apply.
  6. Start debugging:
    1. Add a breakpoint by right-clicking in the code margin and choose Toggle Breakpoint. A breakpoint dot appears.
    2. Launch the debug configuration you created in (5):
      • by clicking the toolbar icon and selecting the configuration (usually JavaAgent)

      • by choosing Run – Debug Configurations, selecting JavaAgent and clicking Debug.
    3. Switch to the Notes client and run the agent via Action menu.  Designer should switch to the debugger.

You can now step through the code!

Just a problem I encountered: if you get this message when running a debug configuration:

it may mean there’s still an open connection. Disconnect first with the appropriate button:

And hey, there’s a handy way to switch between Debug and Domino Designer perspectives too: try CTRL-! You get a popup like this you can use for switching:


Happy debugging!


  1. Thanks for this. Very timely. I ran my java agent which accesses an external API and am getting a security exception. The same code runs fine from Eclipse and I simply exported a JAR file adding it to Domino. Does the Domino agent come into play with security at all ?

  2. Hi Rick,

    Some things from importance:
    1) What is the runtime security level of the agent? Try setting it on 3 (Allow restricted operations with full administration rights)
    2) This should be added in the file [dominoserver-dir]/jvm/lib/security/java.policy:
    grant {
    permission java.lang.RuntimePermission “setContextClassLoader”;
    permission java.lang.reflect.ReflectPermission “suppressAccessChecks”;

    Good luck!

  3. Thanks Martin.

    I did set the agent security to allow restricted operations with full administration rights but still getting the same exception(below)only when I try to create content in the external application (FileNet.) I am authenticating to this external server using my network id. Wondering if the Domino agent is trying to pass a different username then what is used to authenticate with ? I did not try changing the java.policy document yet. My understanding is that any jar file(s) placed in the jvm/lib/ext would be enought authorization ?

    java.security.AccessControlException: Access denied (javax.security.auth.PrivateCredentialPermission com.filenet.apiimpl.wsi.WSICredential read)
    at java.security.AccessController.checkPermission(AccessController.java:108)
    at java.lang.SecurityManager.checkPermission(SecurityManager.java:544)
    at COM.ibm.JEmpower.applet.AppletSecurity.superDotCheckPermission(AppletSecurity.java:1449)
    at COM.ibm.JEmpower.applet.AppletSecurity.checkPermission(AppletSecurity.java:1617)
    at COM.ibm.JEmpower.applet.AppletSecurity.checkPermission(AppletSecurity.java:1464)
    at javax.security.auth.Subject$SecureSet$1.next(Subject.java:1228)
    at java.util.LinkedList.addAll(LinkedList.java:380)
    at java.util.LinkedList.(LinkedList.java:257)
    at javax.security.auth.Subject$SecureSet.(Subject.java:1206)
    at javax.security.auth.Subject.(Subject.java:324)
    at com.filenet.apiimpl.util.Subjects.clone(Subjects.java:48)
    at com.filenet.apiimpl.meta.AccessCache.setAccessible(AccessCache.java:45)
    at com.filenet.apiimpl.meta.Cache.getClassDescription(Cache.java:146)
    at com.filenet.apiimpl.core.ObjectFactory.getSuperClassesFromCMC(ObjectFactory.java:582)
    at com.filenet.apiimpl.core.ObjectFactory.getSuperClassesFromCMC(ObjectFactory.java:566)
    at com.filenet.apiimpl.core.ObjectFactory.getInstance(ObjectFactory.java:546)
    at com.filenet.api.core.Factory$Document.getInstance(Factory.java:7298)
    at com.filenet.api.core.Factory$Document.createInstance(Factory.java:7348)
    at com.maidenre.notestreaty.FolderUtil.createTarget(FolderUtil.java:153)
    at com.maidenre.notestreaty.NotesContractAttachment.processAttachments(NotesContractAttachment.java:89)
    at com.maidenre.notestreaty.NotesP8Transfer.processTransfer(NotesP8Transfer.java:376)
    at JavaAgent.NotesMain(JavaAgent.java:152)
    at lotus.domino.AgentBase.runNotes(Unknown Source)
    at lotus.domino.NotesThread.run(Unknown Source)

    • Rick,
      You get an explicit “Access denied”, so I would think the credentials are malformed or something? I don’t think it’s Domino that tries to prevent this.

  4. Followed the instructions but get this message “server connection failed”. I used Notes 9 beta.

    • There’s a part about “Server connection failed” in the article; did you try this?

      • Yes, I tried. Basically it says this without having any connection. I think some steps are missing from your description.

        – When everything is configures, first start Java Debugging Console
        – Then start debugging with JavaAgent configuration and Eclipse debugger will attach to JVM
        – Go to the agent list and start it, only then breakpoint will fire

  5. hey Martin Vereecken,

    In domino designer I am not able to change the security level as the radio button selection is not changing.
    I am new for domino so please help me

  6. Thanks for sharing.
    I tried without success. I also tried as the Help indicates but it’s also not working.
    I’m not sure what is happening. The code executes and ignores the breakpoints and the debugger. Following the help I added a sleep command to hold the execution while I start the debugger, the same result. The ports are matching.
    Does someone have any idea?

  7. Nice post! This should work locally too right? By that I mean a Java agent inside a local Notes database, and at th moment no server involved.

  8. Got it working! The trick was to add a sleep-function before I do something. As fasr as I understand, that means that the debugger can launch before the agent is finished

    • Glad you figured it out! Thank you for posting your findings!

  9. Can you see class properties under objects in the Variables view ?
    All I get is a useless collection of properties like clsId, isDeleted, etc., but no properties from the class used to instantiate the objects.
    Do you have the same ?

  10. Good tutorial!

  11. Pheww that saved me a lot of time .. Cheers


Submit a Comment

Your email address will not be published. Required fields are marked *

Warning: Use of undefined constant AUTH_KEY - assumed 'AUTH_KEY' (this will throw an Error in a future version of PHP) in /customers/2/8/1/bizzybee.be/httpd.www/wp-content/plugins/wp-math-captcha/includes/class-core.php on line 713 31 − 22 =

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>