This reference intends to guide you in addressing common errors in installing and running the Domino REST API service. Common errors and their corresponding resolutions are described below:
Domino Not Running (First-Time Setup)
If Domino isn't up and running, see Troubleshooting one-touch Domino Setup.
REST API not responding
You get a timeout error when trying to access
yourserver is the DNS name of your Domino server.
You need to check if the REST API is loaded.
- In the Domino server console, type
- If there is no
restapientry in the list, load it using
load restapiin the Domino console.
- If it's listed, shut it down with
tell restapi quitbefore trying
- Take note of any messages in case you need more support.
Check that the REST API is running
The installation, unless told otherwise, added
restapi to the
servertasks in the
You can quickly check on the Domino console if the REST API is running by using
sh ta. In case
restapi isn't listed as running task, load it using
load restapi. The Domino console will output a message on the success or failure to load.
Address already in use error
You get this error when you run the sample script with the sample Notes database:
2021-01-28 15:39:07 ERROR Launch:707 - Management server failed to launch on 0.0.0.0:8889 2021-01-28 15:39:07 ERROR Launch:258 - Fatal java.net.BindException: Address already in use
Stop the process that's using the jar file. Use the Windows Task Manager, or on a Mac/Linux, do this:
ps -eaf | grep launch.class
kill -9 [pid number]
Unable to start the Domino REST API Domino task after updating configuration to use https
KeepManagementURL setting in your
notes.ini is the URL needed for the Domino REST API Domino task to talk to the Java side of Domino REST API. By default this is set to
After updating the URL to
load restapi. For more information, see Domino REST API task.
Database is not fully initialized error
You get this error when you go to your Notes client and:
- Select File → Open → HCL Notes Application.
KeepConfig.nsffile to open.
The following error is shown:
KeepConfig.nsf from the Notes data directory and restart the sample script.
On Mac, the data directory path is
/Users/[userid]/Library/Application Support/HCL Notes Data/.
User ID and password being requested repeatedly when using Notes for Domino REST API testing
Sometimes on the initial starting up of the Domino REST API or creation of KeepConfig and KeepAgents databases, or doing things like creating a folder in mail database, you are prompted for user ID and password repeatedly. This happens if the Don't prompt for a password checkbox under User Security isn't selected or if it gets reset based on the organization's policy.
- Stop your Domino REST API debugging session.
- Go into Notes, and then select File -> Security -> User Security.
- Select the Don't prompt for a password from other Notes-based programs (reduces security) checkbox.
- Exit Notes and restart your Domino REST API debugging session.
This setting can get reset each time you start Notes depending upon your organization's Policy, in which case, you'll need to enable it again.
The Domino REST API uses the Apache log4j2 logging framework. By default logs are stored in the file
domino-keep.log in the sub directory
IBM_TECHNICAL_SUPPORT of your
Notes/Domino data directory.
The log files are set to periodically roll over on a daily basis or when they reach a size of 10MB. Logs are kept for a period of 30 days.
log4j2.properties file controls all of this. If you're looking to make changes to the logging, such as modifying the file name, adjusting the logging destination (like sending it to a log analyzer), or modifying the log level, you can set your own logging parameters.
Familiarity with Apache log4j2 is strongly recommended. The configuration has two steps:
- Specify the location of the configuration file for
Notes/Domino(you can choose any name other than
log4j2.propertiesthat you prefer).
- Provide the file.
It is possible to have several configuration files, but only one will be active at any given time.
Provide your own logging configuration
This guide will show you how to create your own logging configuration. The purpose is to change the logging configuration to your needs. Typically that would be to (temporarily) adjust logging levels like
TRACE or to integrate tools like LogStash.
- Open the
notes.inifile. You may refer to Editing NOTES.INI file.
You can add the
KeepLogConfigFileparameters with the following settings and save. The
KeepLogConfigFileoption can be added to
notes.inito edit the log configuration file.
- You can find the default
log4j2.propertiesfile inside the file
- For example, extract the contents of the
keep-core-1.28.2.jarfile and include the
Just a few things to keep in mind:
- The "
jar" component is included in your Java installation. If your path doesn't lead there, you'll need to indicate the directory to your
- Make sure to specify the version of your
keep-core file, as it may differ from the one shown in the example.
- Make sure to remove the
log4j2.propertiesfile from your Rest API directory to avoid potential issues with upgrades.
log4j.properitesfile for the Domino REST API may undergo changes without prior notice. If you observe any differences in the logging behavior after a recent upgrade, it is recommended to extract and review the updated
- Check out the Log4J documentation for details on the available settings.