🐞Debugging Tips

Some hints and tips to help your problem determination

Common Error Messages

Error Message

Possible Reason

RunJava: Can't find class JAddIn

lotus/notes/addins/jaddin/Squirrel in the classpath. Class names are case-sensitive.

The RunJava task was unable to load the class. Make sure that it is written with exact upper and lower case characters and it can be found by the RunJava class loader

JAddin: Unable to load Java class Squirrel

The JAddin framework was unable to load Squirrel.jar. Make sure that it is written with exact upper and lower case characters.

RunJava: Can't find stopAddin method for class Squirrel.

The Squirrel class must be loaded thru the JAddin framework and not directly from RunJava. Use the command Load RunJava JAddin Squirrel to start Squirrel.

RunJava JVM: java.lang.NoClassDefFoundError: Squirrel (wrong name: sqirrel)

The user class name in the command and the internal name do not match. Most likely you have not typed the name with correct upper and lower case characters.

Out of memory

All Java add-ins execute in a single Java Virtual Machine (JVM) in RunJava. The Domino Notes.Ini parameter JavaMaxHeapSize=xxxxMB may be used to increase the heap space

User is authenticated but not connected

This is a know temporary error in Microsoft Exchange.

Connection Problems

Basic Connection Test

If Squirrel is unable to connect to the Internet mail server, check if a direct connection from the HCL Domino server to the specified Internet mail server is possible. This can be done with Telnet or NetCat (nc).

> nc -v imap.gmail.com 993
Connection to imap.gmail.com port 993 [tcp/imaps] succeeded!

Starting with version 1.6.5, Squirrel performs a basic connection test to the configured mail server before processing messages. Any error found during this test is written to the HCL Domino console (and in log.nsf). The correponding subscription document is not disabled as connection errors are often temporary.

TLS Connection Test

To check which TLS certificate the Internet mail server is using, you may issue the openssl command:

Secure connections are supported by using the TLS variant of the IMAP and POP3 protocol (IMAPS and POP3S). The JVM of the HCL Domino server is using the keystore file domino/jvm/lib/security/cacert to validate the TLS certificates. If the root certificate is not found in the keystore file, you need to add the root (and intermediate) certificates from the connecting mail server into this cacert file.

Add Certificate to Keystore File

To import the missing root and/or intermediate certificates:

HCL Domino 11+:

  1. Open command prompt window with administrator priviledge on the HCL Domino server

  2. cd domino\jvm\bin to change to the directory

  3. Add the certificate to the 'cacert' file, e.g. keytool -import -trustcacerts -keystore jvm/lib/security/cacerts -storepass changeit -alias "New Root CA" -import -file NewRootCA.pem

  4. Restart the HCL Domino server

HCL Domino 9 and 10:

  1. Open command prompt window with administrator privilege on the HCL Domino server

  2. cd domino\jvm\bin to change to the directory

  3. Enter ikeyman to start the IBM Key Management utility

  4. Click Key Database File and then Open. Select the file cacerts in the directory domino\jvm\lib\security. You need to have All files selected to see it. The password to open the file is changeit.

  5. Change to Signer Certificates

  6. Click Add and select the root (or intermediate) certificate you need to import. Click OK and enter any descriptive text for this certificate.

  7. Restart the HCL Domino server.

The following command convers a certificate to PEM format: openssl pkcs12 -in filename.pfx -out cert.pem -nodes

Debugging

For a detailed problem determination, you may use the built-in debugging features.

Enable/Disable Debug

Domino Console Command
Description

Load RunJava JAddin Squirrel Debug!

Start Squirrel add-in in debug mode

Tell Squirrel Debug!

Start the debug mode while the add-in is running

Tell Squirrel NoDebug!

Stop the debug mode while the add-in is running

Squirrel Debug

When activated, the HCL Domino console shows debugging information from the Squirrel add-in and the underlying JAddin framework. The output includes the name of the Java method with the source line number issuing the message. This debuggin information is written to the HCL Domino Console.

While active debugging adds a significant amount of data to the console log and to the log.nsf database, it can be helpful in finding the root of a problem.

Eclipse Jakarta Mail Debug

In addition to the debugging information sent to the HCL Domino console, the Eclipse Jakarta Mail is instructed to create debugging output. Due to the amount of information, the data is written to a separate file with the name Squirrel-Debug-YYYY-MM-YY.log in the HCL Domino data directory.

Don't forget to manually delete these debug files after use.

Debugging OAuth 2.0

Starting with version 1.6.0, Squirrel is using the freeware SOFA for OAuth 2.0 authentication. This framework writes his own detailed logging, which can be configured in the file SOFA-Logging.properties located in the HCP Domino program directory. The resulting log files Squirrel-Debug-OAuth-{n}.log are created in the HCL Domino program directory.

Use the sample file in the distribution package to configure and activate the SOFA debug log.

PreviousMail Server SettingsNextAdministrator Tips

Last updated