Troubleshooting index#
Find the symptom that matches what you see, then read across to the likely cause and the fix. Environment
and provider-side items are phrased as "if you see this, try that" because the exact cause varies by setup;
confirm against your environment before changing anything in production.
Distribution and delivery#
| Symptom |
Likely cause |
Fix |
| The Slack distributor runs but nothing arrives |
The Slack app is missing OAuth scopes, or the bot is not a member of the target channel |
Grant the four scopes (chat:write, files:write, channels:read, groups:read) and invite the bot to every target channel. |
| SharePoint destination reports "not found" |
The browser address-bar URL was pasted instead of the site path |
Use the case-sensitive .../sites/<site>/... form, not the address-bar URL. |
| Writing to a network folder fails |
The Bootstrapper service account lacks write access (the interactive user's access does not count) |
Grant the service account write permission to the folder. |
| SFTP delivery fails to create subfolders |
The server-side account lacks full rights on a dedicated folder |
Give the account full rights on a dedicated destination folder so Reportworq can create subfolders. |
| Email from a non-default From address fails or sends nothing |
The sending identity has no Exchange "Send as" grant |
If you see this, add a "Send as" grant for that mailbox, or send from a dedicated service account. |
| Additional Files do not appear inside the report PDF |
Additional Files ship as separate attachments and are never merged into the PDF |
This is expected. Deliver them alongside the report, or regenerate the content inside the report from a datasource. |
| A burst iteration did not reach the right contact |
Contact mapping matched no field value (matching is case-insensitive but the value must exist) |
Check the mapping field's value; note that a contact named on the burst set wins over mapping. |
| A Teams "Bot" send does nothing |
Teams Bot mode is not wired in this version |
Use Teams Direct (Graph); that is the supported Teams path. |
| Writing output to Box fails |
The Box provider is browse and read-only |
Use a writable destination (for example SharePoint, a network folder, or SFTP) for output. |
Data sources and connectors#
| Symptom |
Likely cause |
Fix |
| Planning Analytics or Cognos integrated auth broke suddenly, often after a Windows update |
The RC4-Kerberos hardening update (KB5073381) can break integrated auth |
If you see this after a Windows update, try enabling AES encryption types (msDS-SupportedEncryptionTypes=28), resetting the account password, and propagating the change. |
PA report cells show #VALUE! |
PAfE Calc Mode is affecting invalid-element rendering and public-vs-private subset resolution |
Review Calc Mode; the error cell is #VALUE! (not #N/A), and Calc Mode also flips SUBNM/DIMNM subset priority. |
| A Pigment connection fails when you save |
The API-export URL does not begin with https://pigment.app/api |
Enter the API-export URL in that exact form; any other URL is rejected at save. |
| A Salesforce connection fails to authenticate |
The Salesforce security token is missing from the password |
Reset the security token in Salesforce (it is emailed) and append it to the password. |
| An Adomd (Power BI / SSAS) connection will not connect |
An MFA account, a non-tabular MDX query, or a non-Premium capacity |
Use a service principal for MFA accounts, write the query as tabular MDX, and target Premium, PPU, or Fabric with XMLA enabled. |
| Re-importing a Pigment block or a relational table created a duplicate |
Re-import adds a new object rather than updating the existing one |
Edit the existing object in place instead of re-importing. |
| A SQL connection exposes credentials or fails to connect |
Credentials are inline, or an ODBC DSN or timeout is mis-set |
Use %USERNAME% / %PASSWORD% substitution, match the ODBC DSN bitness (64-bit) and System-vs-User scope, and note Command Timeout 0 means indefinite. |
| A SQL Server connection fails with "The certificate chain was issued by an authority that is not trusted" |
The SQL Server connector (and the ODBC Driver 18 and the OLE DB Driver 19, Provider=MSOLEDBSQL19, for SQL Server) encrypts by default, and the database server presents a self-signed or untrusted certificate; OLE DB Driver 18 (Provider=MSOLEDBSQL) does not encrypt by default |
Install a trusted certificate on the database server, or on a private network add TrustServerCertificate=True (ODBC: TrustServerCertificate=yes; OLE DB: Trust Server Certificate=True) to the connection string. See Connect SQL Server, OLE DB, and ODBC. |
| Editing one datasource broke many jobs or forms |
Editing, deleting, or disabling a live datasource breaks everything that refreshes from it |
Keep datasource names unique and avoid editing a live one; the blast radius is org-wide. |
Authoring, parameters, and worksheets#
| Symptom |
Likely cause |
Fix |
| A worksheet vanished from the delivered file |
Sheet suppression fired (a cell formula evaluated TRUE, or a provider report returned no data) |
This is expected. Check the suppression formula and the provider data if the sheet should have shipped. |
| A burst recipient received nothing |
The exception check is a whole-report send gate and no exception cell was TRUE |
This is expected. At least one exception cell across any worksheet must be TRUE for the output to send. |
| Cross-workbook formulas return errors |
The referenced workbooks are not co-located in the same Network-Share provider folder |
Co-locate the workbooks in the same Network-Share folder; cross-references across a SharePoint URL fail silently. |
| Copied worksheets reference the wrong sheet |
Cross-sheet references were not rewritten to the sibling copies |
Keep "Copy Worksheets as a Group" on so intra-workbook references retarget the copies; avoid the fragile INDIRECT plus early "Remove All Formulas" workaround. |
| A parameter-set combination was silently skipped |
The parameter-set part count does not match the parameters |
Match the number of pipe-delimited parts; a mismatch is a silent no-op with no error. |
| A report table imported by name comes in empty |
"Show Header Row" was not enabled on the source table |
Enable Show Header Row; use INDIRECT when referencing copied relative ranges. |
Excel and report functions#
| Symptom |
Likely cause |
Fix |
A contributor sees #NAME? in a form |
A write-back formula is in a visible row |
Keep write-back formulas (DBS/DBSW, RWSQLUPDATE/UPSERT, AIINPUT/AIMODELEDINPUT) in hidden rows. |
| A long query string comes out corrupted |
The query is in one cell and a fragment does not start with = |
Split the query across cells and start every fragment cell with =, so its leading quote is not embedded literally. |
Contribution and write-back#
| Symptom |
Likely cause |
Fix |
| A contributor's comments disappeared |
Comments are saved only on Submit, Approve, or Reject; closing the form loses them |
Submit (or approve/reject) to persist comments; do not just close the form. |
| A write to a consolidated cell was dropped |
Proportional Spreading is off, so consolidated writes are rejected |
Enable Proportional Spreading (the PA P-prefix) to spread the value to leaves. |
| A protection password has no effect |
"Restrict editing to input cells" is off |
Turn on "restrict editing to input cells"; the protection password is inert without it. |
| The write-back mailbox will not connect |
POP3 is disabled for the account, or Basic Auth is deprecated |
If you see this, enable POP3 per-account and switch to Modern Auth / OAuth2. |
| Pasting into a form does not apply |
Paste skips non-editable cells and must be a contiguous rectangle |
Paste a single contiguous rectangle that lands on input cells only. |
Scheduling, running, and monitoring#
| Symptom |
Likely cause |
Fix |
| A cron expression is rejected |
An older Quartz ?…? expression was used |
Use a 5-field Cronos expression. |
| A job reports success but produces no output |
An exception gate blocked the send, the data was empty, or the format was not routed to a destination |
Check the exception check, the source data, and that each output format is routed to a destination. |
| You cannot expand or cancel a job you can see |
It belongs to another workspace and its row is redacted in the shared queue |
Switch to that workspace first, then act on the job. |
Install, configuration, and HTTPS#
| Symptom |
Likely cause |
Fix |
| HTTPS will not turn on and the server stays on HTTP |
A bad certificate path silently falls back to HTTP |
If you see this, verify the cert path form (CA is a full .pfx file path; self-signed is a folder path) and that Subject/DNS matches the typed URL, never localhost. |
| The Excel add-in login or M365 features do not work |
The server is running over HTTP |
HTTPS is mandatory for the add-in and all M365 features; enable it. |
| A cluster will not form |
Port 8601 is closed, or the Web App Host is unset |
Open both 8600 and 8601 on every node; set the Web App Host before starting the load balancers. |
| The server runs out of memory under load |
Under-sized for concurrency (peak RAM scales with jobs × threads) |
Size the box for the parallel-execution peak, or reduce concurrency. |
| Report templates went missing after a server migration |
Locally-stored templates do not travel inside the Repository |
Move the local templates separately, and stop the Bootstrap service before swapping the Repository. |
| An in-product update left the server half-upgraded |
The Bootstrap service itself changed in that release |
Do a full reinstall when a release changes the Bootstrap service. |
| Every administrator is locked out |
No admin can sign in through the normal flow |
Open lockout recovery: create lockout-recovery.txt in the installation directory, whose full path every startup writes to the log, then use the Administration Settings cog on the sign-in screen. No restart either way; delete the file when you are done. Browsing from the server console is no longer enough on its own. |
| A license seat is not released after removing a role |
Claims-derived membership still holds the seat |
Clear the "Last Claims" box to release the seat immediately. |
| Entra, SharePoint, and email distributors all broke at once |
They reference the same Microsoft 365 shared credential |
Restore or fix that Microsoft 365 credential in Settings, Integrations, Shared Credentials; one credential can power Entra auth, the SharePoint provider, the Email/SharePoint/Teams distributors, and email collection when each references it. |
| Accounts vanished after switching identity providers |
Switching the active auth provider strands accounts on the old IdP |
If you must cut over (for example to Entra), first provision an admin identity that already exists in the new IdP as a way back in. |
| Symptom |
Likely cause |
Fix |
| AI output used a different model than configured |
The OpenAI Model Id was null, so it fell back to gpt-4o-mini |
Set the Model Id explicitly on the AI provider connection. |
| The Ask-AI chat bot is not visible |
It is not enabled in the current build |
This is the current state. The in-app assistant is not a customer-available capability in this build; report-level AI features are the supported surface. |
The AI* Excel functions do not return generative text |
AI* functions are the Workday Adaptive connector, not generative AI |
Use RWAIINSIGHT for generative insights; the AI* family is Adaptive data retrieval. |
PowerPoint#
| Symptom |
Likely cause |
Fix |
| PowerPoint generation fails |
More than one replicating worksheet is on a slide, or no template is attached |
Put only one replicating worksheet per slide, and attach a .pptx template. |
| A linked shape turned into a plain picture |
The shape was pasted into another deck, which breaks the link |
Keep the linked shape in its original deck. |
| A PowerPoint refresh shows stale or missing data |
Refresh reads from a job-history version, and that history entry was deleted |
Keep the job-history entry the deck refreshes from; refresh never reads the live datasource. |
| Numbers or labels in a cell-range image look squished, overlap, or use the wrong font |
The font the workbook uses is not installed on the Reportworq server, so the picture was drawn with a substitute |
See "Cell-range images (or images pasted into email) look wrong" below. |
Cell-range images (or images pasted into email) look wrong#
A PowerPoint "cell range as picture" is a vector image drawn with the fonts the workbook uses, and it is
re-drawn on the machine that opens the deck. If the font is not installed on the Reportworq server, the
server draws it with a substitute; if the font is not installed on the viewer's machine, the viewer
re-draws it with a substitute. Either way the text can come out squished, overlapping, or clipped. This is
most likely when your report authors work on Windows, where Office fonts such as Calibri, Cambria,
Georgia and Trebuchet MS are always present, but the server runs on Linux, which ships almost no fonts by
default - so both the server render and any non-Windows viewer are affected.
The reliable fix is to make the real font present where the picture is rendered. Options, best first:
- Upload the real fonts to the server, and keep the default EMF format (best, and the recommended answer).
Put the real font files (
.ttf / .otf / .ttc) into a source-report provider folder or the Workspace,
then point Reportworq at that folder under Settings > Configuration > Custom Fonts. The server then
draws the picture with the real font and names it correctly, so the vector stays sharp at any size and
renders correctly for every viewer that has that font (all Windows and Mac-with-Office machines). This is the
complete fix - upload the exact fonts your workbooks use. Because report authors almost always build the
source reports and open the output reports on Windows with the standard Office fonts (Calibri, Cambria,
Georgia, Trebuchet MS and the like), the Linux server that generates those reports in between needs those
same fonts - so upload them.
- Switch the image format to PNG (works everywhere, but raster). In the job's PowerPoint options set
Image Format to PNG. A PNG is a flat picture with no font dependency, so it looks the same on every
machine, including the in-app preview and email. It is not as crisp as EMF if the image is enlarged, and the
server still needs the font to draw the PNG faithfully, so pair it with option 1 for an exact match. There is
no upper limit on Image PPI - raise it for a sharper PNG.
On a Linux server this is the norm rather than the exception, because reports are usually authored and opened
on Windows but generated on Linux in between. For the setup guidance and the strong recommendation to upload
your reports' fonts, see Custom fonts
and the fonts note in Deploy on an Azure Linux VM.
Automation and API#
| Symptom |
Likely cause |
Fix |
| A PowerShell or Turbo Integrator job delivers output but the script never returns |
Invoke-WebRequest is waiting without UseBasicParsing |
Set $PSDefaultParameterValues['Invoke-WebRequest:UseBasicParsing'] = $true in the script. |
An API call to info or history returns 404 |
Those endpoints are deprecated |
Use the current endpoints (ping / list / run / status / cancel). |
| The Cloud API cannot select the right workspace |
A global Cloud key needs a workspace selector once more than one workspace exists |
Append ?workspace=<name> to the request. |
| Launching jobs from Cube Monitoring stopped working |
Cube Monitoring was deprecated |
Migrate job launch to the REST-API Turbo Integrator, which also reaches PA Cloud through the Cloud Connector relay. |
| Every API call returns 400 "REST API not available for this license" |
The license does not carry the API capability |
The REST API and Script Runner are licensed together as the API capability. Check the License tab and contact Reportworq to add it. |
