Troubleshooting#

Symptom → cause → fix, in the order that resolves most reports fastest. Start with the Welisa Error Logs tab: most generation, bulk and signature failures leave a row with the failing context.

First checks#

Right org? Many "bugs" are the right answer from the wrong org. Confirm the org Id in Setup → Company Information (or UserInfo.getOrganizationId()), especially with sandboxes and cloned orgs, whose settings came from the source org.
Active version? A details-only save keeps generating from the previous file. Save as New Version after uploading.
Field in the query? A tag only populates when its field is in the Query Configuration. Check the Copy-Paste Tags tab.

Generation fails with "Error generating document"#

Read the newest Error Log row; it names the operation and the message.
Common causes: the query references a field that does not exist or the user has no access to; a malformed tag (an unclosed {, a missing {/Relationship}); the PDF rendering release update is not enabled (PDF only); a template file larger than the engine can decompose (re-upload with compressed images).

Raw CSS appears at the top of generated PDFs#

Two different causes, and the text tells you which:

Whole CSS rules, braces and all (body { font-family: Helvetica; }): the Visualforce PDF Rendering Service release update is not active. Setup → Release Updates → "Use the Visualforce PDF Rendering Service for Blob.toPdf() Invocations". A greyed-out Enable Test Run button means it is still off; when enabled it reads Disable Test Run. If you cannot enable it, open a Salesforce Support case (wording), then regenerate.
Only selectors, declarations missing (a run-on line like @page body h1 h2 table td, th p .tab): a <style> block sat inside <body> and every {…} pair was treated as a merge tag. Current versions hoist such stylesheets into <head> before merging; a template saved on an older version is fixed by re-saving it.

Merge tags render as literal text#

{Name} appears in the output: the field is not in the query → add it; the tag has a typo (field names are case-sensitive); the template is not the active version → re-save; the editor HTML-encoded the braces; or, for aggregates on very large documents, the function name is lowercase (use SUM, COUNT). CSS in stored HTML can look like unresolved tags but is valid CSS.

Child loop is empty, parent fields are fine#

The Query Configuration was pasted as a full SELECT … FROM … WHERE statement instead of a field-list fragment — child subqueries then never register. Paste the fragment only (Query configuration).
The relationship name is wrong (Contacts, OpportunityLineItems, Lines__r — the exact child relationship name).
The query is right but the generating user lacks Read on the child object or field-level security on its fields. An administrator sees rows a standard user does not:
```
sf data query -o <org> -q "SELECT SObjectType, COUNT(Id) FROM ObjectPermissions WHERE PermissionsRead = true AND SObjectType = 'Contact' GROUP BY SObjectType"
```

Changes are not taking effect#

You saved details without Save as New Version, the upload was not included (the designer warns), or you are looking at a different org. Confirm the version's Pre-Decomposition Status is Complete; if not, re-upload and save again.

Heap size too large#

Rare — dataset size is estimated up front and large jobs route to the background automatically. If you hit it: confirm the package is current (Setup → Installed Packages), reduce the bulk batch size, or switch a Flow to Generate Document (Auto Giant Query). Then tell Welisa the template and record Id — it is a routing case worth knowing about.

Signature e-mails don't arrive#

Check in this order:

Setup → Email → Deliverability must be All email (sandboxes default to System email only and silently drop everything).
The Org-Wide Email Address has Allow All Profiles and is verified (green check).
Daily e-mail limit — Setup → Company Information shows remaining sends.
SPF — the domain's TXT record includes include:_spf.salesforce.com.
DMARC — p=none is fine; p=reject blocks unaligned sends.
DKIM — Setup → DKIM Keys: created, activated, CNAMEs published.

The request's Email Status field shows the exact per-signer error:

sf data query -o <org> -q "SELECT Name, welisa__Status__c, welisa__Email_Status__c, CreatedDate FROM welisa__DocGen_Signature_Request__c ORDER BY CreatedDate DESC LIMIT 5"

PIN e-mail: "Failed to send verification email"#

The guest user needs a verified Org-Wide Email Address with Allow All Profiles, selected as Send Emails From in Signature Settings.

Signing link opens to "Invalid page"#

Most often after moving signing to an Experience Cloud site. In order:

Trailing /s on the Site URL. Signature Settings → Site URL usually ends in /s when copied from the browser (https://acme.my.site.com/signing/s). The package appends the page path itself, so the /s breaks every link. Remove it, save, send a fresh request. Applies to custom domains too.
Pages not on the new site. DocGenSignature, DocGenSignaturePdf, DocGenVerify, DocGenSign must be added to the site that serves signing.
Guest permission set. The new site's guest user needs Welisa Guest Signature; each site has its own guest user.

Both Aura and LWR sites work. Trusted Domains for Inline Frames are not required.

Signing link "Page Not Found" or the wrong domain#

The Site URL points at another org (a cloned sandbox carries the source org's URL). Set this org's own site base URL, no /s.

Signing preview is blank — "Document unavailable" on an Experience Cloud site#

Almost always a site-type setting, not data or permissions: Setup → Digital Experiences → All Sites → your site → Workspaces → Administration → Preferences → enable "Let guest users view asset files, library files, and CMS content available to the site." Save, send a fresh request. Classic Salesforce Sites do not need this. If it still fails, confirm the guest permission set and a verified Org-Wide Email Address.

E-mail logo is blank in the inbox#

The in-app preview blocks external images, so judge by Send Test to a real inbox. WebP is not e-mail-safe — use PNG. Internal Salesforce file links do not render in inboxes — host a public PNG on your website or link a Shared Asset (which publishes a public link; needs Content Deliveries enabled).

PDF image is broken or does not render#

For file-backed images the URL must be relative (/sfc/servlet.shepherd/version/download/<id>); absolute https://… URLs fail silently in PDF. Template images are extracted at save time — an old template may need a re-save. Rich-text images are resolved before merging; broken images in the source field stay broken.

Custom font doesn't render in PDF#

The engine has four fonts and cannot load others. Generate DOCX for custom fonts — Limits.

Long text breaks out of a table cell#

A value with no spaces (an Id, a URL, a SKU) cannot be broken by the engine, and no CSS fixes it. In order: give the column room (about 90 characters per full-width line at 10 pt Helvetica); put the value on its own full-width row beneath its label; make it breakable at the source with a formula field that inserts a space every N characters; for static text you author, insert <wbr/> at every allowed break point. Never use  — it prints visible hyphens into the data. Details: HTML templates.

Large-dataset job stuck in "Harvesting"#

Check Job History for the error and Setup → Apex Jobs for the batch and queueable status. Most common cause: a field in the query configuration was deleted or renamed. Fix the query and re-run.

Chart comes out blank in the PDF#

In HTML → PDF output only the CSS-bar styles render (bar, pivot, clustered, stacked); column, pie, donut, line and area need inline SVG, which the PDF engine drops. Use a Word template for those shapes, or switch style. A Long Text Area cannot be grouped by — pick a Text, Picklist, Number, Date or Checkbox field.

A value is missing from the Type picklist#

Creating or editing a template, Type lacks Word / PowerPoint / Excel / HTML / PDF / Canvas, so that kind of template cannot be created — or saves as Word and opens to an empty designer.

Who this affects: orgs that were installed before that value existed. A restricted picklist value never reaches an already-installed org, and no later upgrade brings it; fresh installs always have the full list. Creating one by API fails with INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST.

Type lives on two objects, and both matter: Welisa Template (what you pick when creating) and Welisa Template Version (how the template actually behaves — the editor that opens, how the body is parsed). A template that says HTML while its active version says Word behaves as Word.

Fix, on both objects:

Setup → Object Manager → Welisa Template → Fields & Relationships → Type → Values.
Confirm Word, PowerPoint, Excel, HTML, PDF, Canvas are present and Active; activate any that are deactivated.
If a value is absent, add it with New, spelled exactly as above. Adding a value to this managed picklist is allowed and works like one that shipped.
If the object uses record types, add the values to each record type's available list.
Repeat for Welisa Template Version.

Fixing the picklist does not retype existing records: open the template, set Type, then open its active version and set Type there too.

"Single" signing order fails on an upgraded org#

INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST, Signing Order: bad value … Single — same mechanism as above. Setup → Object Manager → Welisa Signature Request → Signing Order → New → add Single.

A template created outside the designer opens to an empty canvas#

The designer loads the body from a specifically titled file that a scripted or API-created template does not have; the template generates fine but opens blank. Re-save it once through the template editor.

Permission set error during an upgrade#

PermissionSet(DocGen_User) The user license doesn't allow the permission: View All welisa__DocGen_Template__c — Welisa User or Welisa Admin is assigned to a user whose licence (Chatter Free, Identity, Community) does not permit View All. Remove those assignments and retry (Installation).

Still stuck?#

Check the Welisa Error Logs tab first. Then contact your Welisa consultant or [email protected] with: the org Id, the template name and type, the record Id, the output format, the newest error-log rows, and — for signing problems — the request's Email Status. Handy queries:

# Signature settings (site URL, sender address)
sf data query -o <org> -q "SELECT welisa__Experience_Site_Url__c, welisa__Signature_OWA_Id__c FROM welisa__DocGen_Settings__c"
# Sites and public domains
sf data query -o <org> -q "SELECT Domain.Domain, Site.Name, PathPrefix FROM DomainSite"
# Org-Wide Email Addresses
sf data query -o <org> -q "SELECT Id, Address, IsAllowAllProfiles, Purpose FROM OrgWideEmailAddress"
# Template versions and their query configuration
sf data query -o <org> -q "SELECT welisa__Template__r.Name, Name, welisa__Is_Active__c, welisa__Type__c, welisa__Pre_Decomposition_Status__c FROM welisa__DocGen_Template_Version__c ORDER BY welisa__Template__r.Name"