Batch Processing Troubleshooting — Common Errors and Fixes in Dochly

Updated June 2026 10 min read Batch Processing

This guide covers every category of batch processing error in Dochly — jobs that won't start, report validation failures, per-record generation errors, email delivery problems, scheduled jobs that don't trigger, duplicate documents, and storage failures. Each error includes the most likely causes and exact steps to fix it.

First checks before troubleshooting

Check the job log first

Most batch errors are documented in the job log with an exact error reason per record. Before investigating further, open Dochly → Batch Jobs → Job History → [Job Name] and read the failure rows. The error reason text usually identifies the fix directly.

Verify the source report independently

Run the source report directly in Salesforce Reports. Confirm it returns the expected records and that the ID column is present. Many batch issues trace back to a report that has changed, moved to a personal folder, or returned unexpected results.

Test the template with a single record

If generation is failing on multiple records, test the template individually: open a record from the failing set and use Dochly → Generate Document (single record mode). If single generation also fails, the issue is in the template — not the batch configuration.

Confirm Dochly connection is active

Dochly → Settings → Connection Status must show green. An expired or disconnected connection causes all batch jobs to fail at the API call stage. Re-authenticate if the status shows yellow or red.

Job won't start or stays queued

Job stays in Queued status for more than 10 minutes

Symptom: Job appears in Active Jobs as Queued but never moves to Processing. Progress stays at 0%.

Most likely causes

Salesforce async Apex queue is at capacity — too many concurrent async jobs across the org
Another large Dochly batch job is consuming available async workers
Salesforce is experiencing a platform delay — check trust.salesforce.com for org-level incidents

How to fix

Check Setup → Apex Jobs → Scheduled and Queued jobs — if the queue is full with other jobs, wait for them to clear before your job picks up
Check trust.salesforce.com for any active incidents on your Salesforce instance
If the queue is clear and the job still hasn't started after 15 minutes, cancel it and relaunch — occasionally async submissions get stuck and a fresh submission resolves it

Launch button is greyed out or "New Batch Job" is not accessible

Symptom: Cannot create or launch a batch job. The New Batch Job button is disabled or the Batch Jobs tab is missing.

Most likely causes

The Dochly Admin permission set is not assigned to your user — only Dochly Admin can create batch jobs
No Active templates exist in the org — batch jobs require at least one Active template
Dochly connection is disconnected — batch jobs cannot be launched without an active connection

How to fix

Setup → Users → [Your User] → Permission Set Assignments — confirm Dochly Admin is listed
Dochly → Templates — confirm at least one template has status Active (not Draft)
Dochly → Settings → Connection Status — reconnect if the status is not green

Report validation errors

Report fails Dochly validation with "ID column not found"

Symptom: After selecting the report in the batch job panel, Dochly shows a validation error that the Record ID column is missing.

Most likely causes

The report was built without adding the Record ID field as a column
The report uses a custom ID field rather than the standard Salesforce ID field

How to fix

Open the report in Salesforce → Edit → add the Record ID column (field label: "Opportunity ID", "Account ID" etc. — the standard 18-character Salesforce ID field for the object)
Save the report and re-select it in the batch job panel — validation should now pass

Report validation error: "Report not accessible" or "Report not found"

Symptom: A report that exists in Salesforce cannot be selected in Dochly, or was previously working but now fails validation.

Most likely causes

Report was moved to a personal folder — Dochly cannot access reports in personal folders
Report was deleted or renamed after being saved to a batch job configuration
The Dochly system user doesn't have access to the folder containing the report

How to fix

Open the report in Salesforce → click the folder name in the breadcrumb → confirm it is a Public or shared folder (not "My Personal Custom Reports")
If in a personal folder: Reports → click the report's dropdown → Move → select a public folder
If the report was deleted, recreate it and update the batch job configuration to point to the new report

Generation failures on specific records

Some records fail with "Template generation error" while others succeed

Symptom: The job completes with failures. Failed records show "Template generation error" or "Merge field error" in the job log. Successful records have documents; failed records do not.

Most likely causes

A required merge field in the template is blank on the failing records but populated on the successful ones
A formula field referenced in the template throws an error on specific records due to a data edge case (e.g. division by zero, null parent reference)
A conditional logic branch references a field that is null on only some records

How to fix

Open one of the failing records in Salesforce — compare its field values to a successfully generated record. Identify the field that differs (blank vs populated)
For merge fields that may be blank: add a default value filter in the template: {{Field__c | default: "N/A"}}
For formula field errors: check the formula on the affected records in Salesforce — formula errors show as #Error in the record. Fix the formula or the underlying data
Run a targeted re-job for the failed records only after fixing the data issues

Records fail with "Insufficient access" or "Field not accessible"

Symptom: Batch job failure log shows permission-related errors for specific records or fields.

Most likely causes

The Dochly system user's profile or permission set doesn't have Read access to a field used in the template
Salesforce sharing rules restrict the Dochly system user from accessing certain records
Field-level security was changed after the template was built — a field that was accessible is now restricted

How to fix

Setup → Object Manager → [Object] → Fields → [Field] → Field Accessibility — confirm the Dochly system user's profile has Read access
Setup → Sharing Settings — confirm the org-wide default or sharing rules allow the Dochly system user to access the affected records
For org-wide changes: Setup → Users → [Dochly System User] → verify the profile and permission sets still include all required object and field permissions

Email delivery failures

Batch job completes but recipients did not receive email

Symptom: Job log shows success for all records, but customers report not receiving the email with the attached document.

Most likely causes

Emails landed in spam or were filtered by the recipient's email security system
Org-level Salesforce email deliverability is set to "System email only" — blocking outbound customer-facing email
The daily Salesforce email limit (5,000 emails/day for most orgs) was hit during the batch run — emails after the limit are dropped silently
The email delivery field (Contact.Email) contained an invalid or inactive address

How to fix

Setup → Deliverability → confirm Access Level is "All email" (not "System email only")
Setup → Email Log Files — generate a log for the batch run date/time window and check for delivery failures or bounces per address
For large batches approaching 5,000 emails: split into multiple jobs run on different days, or use Salesforce Mass Email or Marketing Cloud for high-volume sends
Ask recipients to check spam/junk folders and whitelist the sending domain

Individual records fail with "Email field is blank"

Symptom: Job log shows specific records as failed with error reason "Contact.Email is blank" or similar.

Most likely causes

The email field is empty on those specific records — contact data is incomplete
The wrong email field is configured as the delivery recipient — e.g. Account.Email instead of Contact.Email

How to fix

Populate the email field on each failed record — or update via a mass update if many records are affected
Check the delivery field configuration in Dochly → Batch Jobs → [Job] → Delivery Settings — confirm the correct email field is selected
Add the email field as a column in the source report filter — "Email is not blank" — to exclude records without email addresses from future runs

Scheduled job not triggering

Scheduled job did not run at the expected time

Symptom: The scheduled time passed but no job appears in Job History and no notification email was received.

Most likely causes

The schedule was deactivated (accidentally or by another admin) before the trigger time
The timezone configured on the schedule doesn't match the org's timezone — the job ran at the wrong local time
The Salesforce scheduled Apex job was aborted — check Setup → Apex Jobs → Scheduled Jobs
Salesforce had a platform incident at the exact trigger time — check trust.salesforce.com for the relevant date/time

How to fix

Dochly → Batch Jobs → Scheduled Jobs — confirm the job status is Active and the "Next run" datetime matches what you expect
Setup → Apex Jobs → Scheduled Jobs — confirm the Dochly scheduled job appears and its Next Scheduled Run is correct in UTC (Salesforce stores scheduled Apex in UTC — convert from your local timezone)
If the Apex job is missing: deactivate and reactivate the Dochly schedule to recreate the Apex scheduled job entry
Verify the timezone in the schedule configuration matches the timezone the times are expressed in

Duplicate documents generated

Records have multiple copies of the same generated document

Symptom: A record's Files list contains 2 or more copies of a document that should only exist once — typically after a re-run or a scheduled job.

Most likely causes

No prevention field is configured — the same records are included in every batch run because the report filter doesn't exclude already-processed records
A manual re-run was launched on top of a scheduled run that also fired — both processed the same records
The prevention field was reset prematurely before the next batch cycle was intended to start

How to fix

Configure a prevention field (checkbox) on the object and add a report filter for that field being FALSE. Configure a post-generation update to set it TRUE. See Schedule a batch run for the full prevention field pattern
For existing duplicates: delete the older file versions from the affected records' Files lists. Sort by Created Date to identify which is the correct (most recent) version to keep
If using scheduled jobs: do not also run manual "Run Now" jobs covering the same record set on the same day

Storage and file errors

Batch job fails midway with "Storage limit exceeded" errors

Symptom: Job starts processing but fails with storage errors after some records are generated. Later records show "File storage limit exceeded" in the job log.

Most likely causes

The Salesforce org has reached its File Storage limit — no more files can be created
A very large batch run was started without checking available storage first

How to fix

Setup → Storage Usage — check available File Storage. If near the limit, free space by archiving or deleting older files before re-running
Estimate required storage before large runs: average document size (KB) × number of records = total storage needed. Confirm this is available before launching
Consider using an external storage destination (e.g. SharePoint or Google Drive via Dochly integrations) for large-volume batch runs to avoid consuming Salesforce file storage

Quick-reference error table

Symptom	Most likely cause	Fix
Job stays Queued >10 min	Apex queue full or Salesforce platform delay	Check Apex Jobs queue; check trust.salesforce.com; relaunch if needed
New Batch Job button disabled	Missing Dochly Admin permission or no Active template	Assign Dochly Admin permission set; set a template to Active
Report validation: ID column not found	Report missing the Record ID column	Add the standard ID field column to the report
Report not accessible	Report in personal folder or deleted	Move report to a shared public folder
Generation error on some records	Blank required field or formula error on specific records	Open failing record; fix missing data; re-run targeted job
Insufficient access errors	Dochly system user missing field/record access	Check field-level security and sharing rules for the system user
Emails not received	Deliverability off; daily limit hit; spam filtering	Check Setup Deliverability; check Email Log; split large runs across days
Email field blank errors	Contact.Email empty on specific records	Populate email field; filter report to exclude blank email records
Scheduled job didn't fire	Schedule deactivated; timezone mismatch; Apex job aborted	Check Scheduled Jobs in Dochly and Apex Jobs in Setup; reactivate if needed
Duplicate documents on records	No prevention field; job ran twice against same records	Configure prevention checkbox field with post-generation update
Storage limit errors mid-run	Salesforce File Storage at capacity	Check and free storage before running; use external storage for large volumes

Support checklist — what to include when contacting Dochly support

If the issue persists after working through the relevant sections, include this information when contacting support for the fastest resolution.

1
The batch job name and its current status (Queued / Processing / Completed with failures / Cancelled)
2
A screenshot of the job log summary — showing total, success, failure counts, and duration
3
The exact error reason text from 2–3 of the failing records in the per-record log
4
The Salesforce Record ID of one specific failing record — so support can investigate the data on that record
5
The template name and whether single-record generation also fails for the same record
6
The source report name and whether the report validates successfully when you select it in the job panel
7
For scheduled job issues: the schedule configuration (frequency, time, timezone) and the exact time the job was expected to run vs when it actually ran (or didn't)
8
Whether this is a new issue (worked before and broke) or has never worked — and any recent changes (template edits, permission changes, report moves, Salesforce releases) that may coincide

Frequently asked questions

When a working batch job starts failing without template changes, the issue is almost always in the data or environment: (1) A field that was always populated is now blank on some records — data quality has degraded; (2) A Salesforce release changed how a formula or flow populates data; (3) Field-level security or sharing rules were updated, restricting the Dochly system user; (4) The source report was moved, renamed, or its filters were changed. Check each of these systematically and compare a failing record's data against a previously successful record.

Dochly reads the report at the moment the job starts. If the report uses relative date filters and some records moved out of scope between when you checked the count and when the job ran (e.g. a deal was re-opened and no longer matches "Closed Won"), the job processes fewer records than the preview showed. This is expected behaviour — the job correctly processes only the records that match the report at run time. Check the report again with the same filters to see the current count.

Yes — the most reliable approach is to create a new Salesforce report filtered to only the failed record IDs. In the report, add a filter: Record ID IN [list of failed IDs from the job log]. Run a new batch job against this targeted report. If you have a prevention field configured, successful records from the original run won't appear in the re-run report because their prevention field is already TRUE — only the failures (which never had the field set) will be included.

Batch Processing series complete

You've covered the full Dochly Batch Processing series — setup, running jobs from reports, scheduling recurring runs, monitoring and tracking results, and troubleshooting every common error. Your batch document workflows are now production-ready.

Batch Processing series Return to the full series overview Document Generation series Triggers, formats, flows and scheduling Conditional Logic series Dynamic templates for any record Full Help Center All Dochly guides and documentation