ShowTable of Contents
Introduction
This FAQ document addresses the issue of server scheduled agents that either don't run at all, or run at the wrong time.
Basic Principles
Scheduled agents are not, generally speaking, guaranteed to run at the
exact time you specify. If the server is busy doing other things, it waits to run the agent until it has the resources available. The most common limiting factor is the number of agents that can execute simultaneously. This value is set by an administrator. If an agent is delayed, it's often the case that all available threads were taken up by other agents.
Agents that run "after mail received" or "when documents created or modified" are also not executed immediately, but should normally run within a few minutes. These, too, are affected by whether there are free agent threads available.
Scheduled agents and "when documents created or modified" agents will generally run once when they are edited or enabled. If the agent is running unexpectedly, check its "last modified" time and see whether it was modified just before it ran. This might be happening because of the DESIGN task on the server.
The server limits the amount of time an agent is allowed to run; if it exceeds this time, the agent manager will terminate it. This time is adjustable, but use caution adjusting it, because this is your control against runaway agents with infinite loops tying up the agent threads, slowing the server and preventing other agents from running. If your agent takes too long to run, first look at whether it can be written more efficiently, or whether it can run more frequently so it has less work to do each time.
Servers also have a setting for how long an agent may be delayed before the server decides that it should be skipped altogether. This is normally is set to a large enough figure that it will not affect things unless the delay is extreme, on the order of days. However, if there are so many long-running agents on the server that they can't all complete within
24 hours, agents may get pushed back later and later each day, until some do exceed this limit. If agents are failing to run for this reason, this will be clear from the server log.
Collect Information
- View the agent's log by selecting the agent in Domino Designer and using the menu Design / View Log.
- Open the agent in Designer and check its schedule. Look at the start and end times. See whether there are any error messages in the log pertaining to the agent. Make sure it's set to run on the correct server.
- Check the server log (log.nsf, Miscellaneous Events view) to see what happened when the agent ran (or when it was supposed to have run). Look for the agent start and end times, and see whether there seem to be any error messages associated with the agent. If the agent started late, look at previous log entries to see what happened before the agent ran, that might have delayed it from starting.
- Look at the most recent entries in the log.nsf, which will give you some idea of what time the server thinks it is now. If the server's clock is misadjusted, this can of course result in things running at the wrong times. Check what time zone is shown on the log entries; it might be that the server's time zone is different from what you expected.
Does Not Run
If the agent log says the agent ran, the agent did run. People sometimes think an agent isn't running when actually it ran, but didn't do what they expected it to. Often this is because it had an unexpected error and terminated early. In case of an error, the server log will generally contain a line giving the error message.
Agents can prevent most early exits by trapping errors and handling them internally. For instance, in LotusScript, use the
On Error statement. If the code handles the error, no message will appear in the log. However, if the agent handles the error badly, it might fail to accomplish its task, with no indication in the log of the cause of the failure. It's usually a good idea to have your error trap generate some output, for instance using the LotusScript
Print statement and including the values of
Err,
Error, and
Erl functions, so that by reading the server log you can tell what went wrong.
LotusScript has a "remote debugger" to let you step through server agents, but this is a last resort on a production server, because it requires administrator intervention to enable and disable, and causes a delay in all server agents to give you time to connect to the agent before it gets started.
NOTE: The NotesUIxxx classes may not be used in a server agent. They will cause the agent to abort with the log message, "Error creating product object."
Mail Sending
Another thing that may make people conclude that an agent isn't running, is that users don't receive email it was supposed to send out. This can be especially perplexing when the agent sends email just fine when you run it manually from a client.
Email sending by a server can fail because the server isn't configured correctly to send mail. This may in some cases result in an error you can see in the log, while in other cases the mail may end up just sitting in the server's mail.box, waiting to be delivered until the server can make a connection to another server, which never happens. For formula agents, @MailSend may fail silently in cases where the email address of the recipient can't be resolved (perhaps you can detect the failure by checking the return value of @MailSend).
If using the [IncludeDocLink] option of @MailSend, see the technote in the references below.
The Mail Routing Events view of log.nsf may contain information to help diagnose the problem, but generally, if email sending isn't working, you should work with the server administrator to get it straightened out.
In case the server's directory is missing information about your recipients, it's generally a good idea to make the address as complete as possible. Don't send the email to "John Hootnode", but use the canonical name and domain if you've got it, e.g. "CN=John Hootnode/O=Yoyodyne@EIGHTHDIM".
References