A scheduled function in Zoho CRM runs while nobody is watching, which is exactly why it is hard to debug. When a nightly script does nothing, or does the wrong thing to two hundred records, you need a way to see what it did and why. This guide covers the tools Zoho CRM gives you, a step-by-step method for finding the problem, and the errors that cause most failed schedules. It belongs to the Zoho Deluge hub; for building schedules in the first place, see automating Zoho CRM with scheduled functions.
Where Schedules Live and How They Run
Schedules are set up in Zoho CRM’s setup area under automation, where each one points to a Deluge function and a timetable: once, daily, weekly, monthly or at a set interval. The function runs on Zoho’s servers as the user who created the schedule, with that user’s permissions, and its runs are listed in the schedule’s execution history.
Step 1: Run the Function Manually First
Never debug through the schedule. Open the function in the editor and run it directly, so you see the output immediately instead of waiting for the next run. If the function expects a record, give it one known test record whose values you can check by hand.
Step 2: Make the Function Talk
Deluge’s info statement writes a line to the output and the log. Add one after every step that matters, so you can see what the script found and what it decided.
records = zoho.crm.searchRecords("Deals", "(Stage:equals:Proposal)");
info "Deals found: " + records.size();
for each deal in records
{
info "Checking: " + deal.get("Deal_Name") + " | Closing: " + deal.get("Closing_Date");
if(deal.get("Closing_Date") != null && deal.get("Closing_Date") < zoho.currentdate)
{
resp = zoho.crm.updateRecord("Deals", deal.get("id"), {"Stage":"Stalled"});
info "Update response: " + resp;
}
}Three things to log every time: how many records the search returned, the values the decision depends on, and the response from every update or API call. Most bugs show up in one of those three lines.
Step 3: Read the Execution History
After a scheduled run, open the schedule’s execution history. Each run shows whether it succeeded or failed, and failed runs carry the error message and the line it stopped on. Compare a failed run with the manual run from step 1: if the manual run works and the scheduled one fails, the difference is usually permissions, the time the run happened, or data that changed in between.
Step 4: Catch Errors Instead of Stopping
One bad record should not stop a run over five hundred good ones. Wrap the work for each record in a try and catch block, log the error with the record’s ID, and carry on.
for each deal in records
{
try
{
resp = zoho.crm.updateRecord("Deals", deal.get("id"), {"Stage":"Stalled"});
if(resp.get("id") == null)
{
info "Update failed for " + deal.get("id") + ": " + resp;
}
}
catch (e)
{
info "Error on " + deal.get("id") + ": " + e;
}
}The Errors Behind Most Failed Schedules
| Symptom | Usual cause | Fix |
|---|---|---|
| Runs but changes nothing | The search returns no records, often a criteria typo or the wrong API field name | Log the search count; check the field’s API name in setup |
| Fails on some records only | A field is empty on those records | Check for null before using a value |
| Stops partway through | Too many records or API calls for one run | Process in pages, or split into smaller batches |
| Update response shows an error | A mandatory field, validation rule or layout rule blocks the update | Read the response message; include the required fields |
| Works manually, fails on schedule | The schedule runs as a user without access to the module or records | Create the schedule as a user with the right permissions |
| Dates are a day off | Time zone differences between the schedule and the data | Compare with zoho.currentdate and test around midnight |
Search functions return a limited number of records per call, so a script that must handle more than one page of results should loop through pages until a call returns fewer records than the page size. Check Zoho’s current Deluge and API limits for your edition before designing a large batch job.
Testing Without Touching Live Data
A scheduled function that updates records can do damage quickly. On Enterprise and Ultimate, build and test in a sandbox first. Without one, add a condition that limits the script to records you control, for example a test tag or a single owner, and remove it only when the output is correct. Before a large update, export the affected records, so you can restore values if something goes wrong.
Writing Schedules That Are Easy to Debug
- Keep each schedule to one job; a schedule that does five things fails in five places.
- Log a one-line summary at the end: records found, updated, skipped and failed.
- Use descriptive variable names, so the log reads like a sentence.
- Store settings such as stage names and day counts at the top of the function, not buried in the logic.
- Note in a comment who owns the schedule and what it is for.
Monitoring After Go-Live
Check the execution history after the first few runs and then weekly. For important jobs, have the function send a short email or Cliq message with its summary counts, so a silent failure is noticed the next morning rather than at month end.
A Debugging Checklist
- Run the function manually on one known record.
- Log the search count, the deciding values and every response.
- Read the latest execution history entry and its error line.
- Check API field names, null values and mandatory fields.
- Confirm the schedule’s owner has the right permissions.
- Add try and catch per record, then let the schedule run again.
- Remove noisy info lines once it is stable, but keep the summary counts.
When to Get Help
If a schedule touches many modules, external APIs or thousands of records, a review by a developer saves time and protects your data. ABR’s Zoho CRM developer services cover building and fixing Deluge functions, and the Deluge cheat sheet is a quick reference for syntax.
Frequently Asked Questions
How do I see why a Zoho CRM schedule failed?
Open the schedule’s execution history; failed runs show the error message and the line where the function stopped.
How do I debug a Deluge function?
Run it manually on a known record, add info statements after each important step, and read the output and logs.
Why does my schedule work manually but fail when scheduled?
Usually because the schedule runs as a user without access to the module or records, or because the data changed between runs.
How do I stop one bad record breaking the whole run?
Wrap the work for each record in try and catch, log the error with the record ID, and continue.
Is there a limit on how many records a schedule can process?
Yes, there are limits on records per search and on API calls; process large sets in pages and check Zoho’s current limits for your edition.
Who should own a scheduled function?
A user with permission to every module and record the function touches, ideally a dedicated admin account.
