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. |
| 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 share one Azure app registration | Restore or fix the single app registration; it powers Entra auth, the SharePoint provider, the Email/SharePoint/Teams distributors, and email collection. |
| 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. |
AI#
| 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. |
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. |
Feedback on this page
Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.
Email feedback on this pageOr write to support@reportworq.com directly.