Introduction
Debugging is an essential skill for every HCL Notes developer. While writing LotusScript is important, being able to quickly identify and resolve issues is what makes development efficient.
This article covers 15 practical debugging techniques that you can use in real world Notes applications.
1. Use Print Statements for Quick Debugging
The Print statement writes output to the Domino server console (for agents) or the Notes status/debug console, depending on where the code is running.
Example
Print “Agent Started”
Print "Current User: " & session.EffectiveUserName
Print "Database: " & db.FilePath
Best Use:
Scheduled agents
Server agents
Quick execution tracing
2. Display Variables with MessageBox
For client-side scripts, MessageBox is a simple way to verify values.
Dim total As Integer
total = 150
MessageBox "Total Amount: " & total
Best Use:
Action buttons
UI events
Field events
Avoid leaving MessageBoxes in production code.
3. Verify Objects Before Using Them
A common LotusScript error is:
Error 91: Object variable not set
Always check object references.
If doc Is Nothing Then
MessageBox “Document not found.”
Exit Sub
End If
4. Log Execution Flow
Track the script’s progress by logging key milestones.
Print “Step 1: Database opened”
Print “Step 2: View retrieved”
Print “Step 3: Document found”
If execution stops unexpectedly, you will know where the problem occurred.
5. Use Structured Error Handling
Always include an error handler.
On Error GoTo ErrorHandler
’ write your code here
Exit Sub
ErrorHandler:
MessageBox "Error " & Err & ": " & Error$
This provides meaningful information instead of an abrupt script failure.
6. Use the LotusScript Debugger
The built in debugger in Notes Designer allows you to:
–Set breakpoints
–Step through code
–Inspect variables
–Watch object values
Useful commands:
Command Shortcut Purpose
Step Into F8 Executes the current line and enters called procedures or functions.
Step Over Shift + F8 Executes the current line without entering called procedures.
Continue F5 Resumes execution until the next breakpoint or the end of the script.
Toggle Breakpoint F9 Adds or removes a breakpoint on the current line.
Best Use:
Set breakpoints near the suspected problem instead of stepping through the entire application.
Use Step Into only when you need to inspect a procedure.
Use Step Over for trusted or frequently called routines to save time.
Combine the debugger with structured error handling for faster diagnosis.
Remove unnecessary breakpoints after completing your investigation.
7. Inspect Document Fields
Print field values to confirm they contain the expected data.
Print "Status: " & doc.GetItemValue(“Status”)(0)
Print "Priority: " & doc.GetItemValue(“Priority”)(0)
This is especially helpful when troubleshooting computed fields or workflow logic.
8. Log to a Database Using NotesLog
Instead of displaying messages, log them.
Dim log As New NotesLog(“Order Processing”)
Call log.OpenNotesLog(db.Server, “log.nsf”)
Call log.LogAction(“Agent Started”)
Call log.Close
Best Use:
Centralized logging
Persistent records
Easier troubleshooting in production
9. Write Debug Information to a Text File
When database logging isn’t practical, write to a local file.
Dim fileNum As Integer
fileNum = FreeFile()
Open “C:\Temp\Debug.txt” For Append As fileNum
Print #fileNum, Now & " - Processing document"
Close fileNum
Note: Ensure the target directory exists and the process has write permissions.
10. Display Document Identifiers
When troubleshooting document-specific issues, log the UNID.
Print "UNID: " & doc.UniversalID
This makes it easy to retrieve the document later for investigation.
11. Verify View Lookups
Confirm that a document is actually returned by the view.
Set doc = view.GetDocumentByKey(“E1001”, True)
If doc Is Nothing Then
Print “Document not found.”
Else
Print “Document found.”
End If
This helps distinguish lookup problems from data problems.
12. Check Field Existence Before Reading
Avoid assuming every field exists.
If doc.HasItem(“Comments”) Then
Print doc.GetItemValue(“Comments”)(0)
Else
Print “Comments field not found.”
End If
This prevents unexpected behavior when fields are optional.
- Time Long-Running Operations
Measure execution time to identify performance bottlenecks.
Dim startTime As Double
startTime = Timer
Print “Elapsed Time: " & Format(Timer - startTime, “0.00”) & " seconds”
14. Debug Multi Value Fields
Print every value in a multi-value field.
Dim values As Variant
Dim i As Integer
values = doc.GetItemValue(“Categories”)
For i = LBound(values) To UBound(values)
Print values(i)
Next
This helps verify that all expected values are present.
15. Create a Reusable Debug Routine
Instead of repeating Print or MessageBox statements throughout your code, create a helper procedure.
Sub DebugMessage (msg As String)
Dim debug As Boolean
debug = True ’ Enable debugging
'debug = False ’ Disable debugging
If debug Then
Print “Debug place 1” & " : " & msg
End If
End Sub
Usage:
Call DebugMessage(“Starting document validation”)
Call DebugMessage(“Processing complete”)
Best Use:
Only one place to change debug behaviour.
Easy to add timestamps.
Cleaner application code.
Can later be modified to write to a log file or database instead of the console.
No need to delete debug statements.
Enable or disable debugging by changing a single variable.
Keeps the code clean and readable.
Useful during development and testing.
This makes it easy to switch between console output, file logging, or database logging later.
======Common Debugging Mistakes ==========
–Mistake Better Practice
–Leaving MessageBox calls in production Remove or replace with logging
–Using On Error Resume Next everywhere Use structured error handling
–Assuming objects exist Check for Nothing first
–Ignoring document UNIDs Log them for traceability
–Reading fields without HasItem() Validate optional fields
–Recommended Debugging Workflow
–Reproduce the issue consistently.
–Add logging around the suspected code.
–Verify object references.
–Inspect document field values.
–Use the LotusScript debugger for step-by-step execution.
–Review error logs and server console output.
–Remove or disable debug statements once the issue is resolved.
Summary
–Technique Primary Use
–Print Console/debug output
–MessageBox Quick client-side checks
–Error Handler Capture runtime errors
–NotesLog Persistent logging
–Debugger Step-by-step execution
–Field inspection Validate document data
–Timing Performance analysis
–Helper routine Consistent debugging output
Conclusion
Effective debugging is about using the right tool for the situation. MessageBox is useful during UI development, Print works well for tracing execution, and NotesLog provides persistent records for production environments. Combined with structured error handling and the LotusScript debugger, these techniques can significantly reduce the time spent diagnosing and fixing issues in HCL Notes applications.
By building debugging into your development process not just after something breaks you will create applications that are easier to maintain, troubleshoot, and support over time.