[Troubleshooting] Error Rendering Report In Ambience 202x & Repertoire 202x

Repertoire 2022+
,
1

Overview

This guide explains how to resolve error rendering report failures in Ambience 202x & Repertoire 202x. The error occurs due to the rendering engine cannot locate the correct runner to process jobs, resulting in failed report output.

Step 1: Identify The Error

You may see log entries similar to:

10:31:01.327 INFO  ambience.docxengine.RenderHelper - Error rendering report. 
Status: Error(Unexpected error: ambience.queue.QueueManager$WaitTimeoutException: WaitTimeout qId=cf9929f8-b84f-494e-bcf5-80c5ce681a55,Iterable())

The Error Rendering Report message is the primary failure. The WaitTimeoutException occurs because the job is stuck in the queue with no runner available to process it. In other words, the system keeps waiting for a handler that never arrives, until the timeout threshold is reached.

Step 2: Verify The Runners

In your application.conf file, locate the ambience.queue.runners block. This section defines the job runners responsible for handling different types of tasks (such as DocX, ETL, and RML). A properly configured block should look like this:

ambience.queue {
  runners: {
    "docx" : "ambience.docxengine.queue.DocXJobRunner"
    "etl"  : "ambience.etl.runtime.queue.ETLJobRunner"
    "rml"  : "ambience.rmlengine.queue.RMLJobRunner"
  }
}

Each runner ensures that jobs of its type are picked up and processed correctly. If any of these entries are missing or misconfigured, reports will remain stuck in the queue and eventually fail with an error shown in Step 1.

Checks and actions to perform:

  • Ensure all required runners (docx, etl, rml) are present in the block.
  • Verify each runner’s class path is spelled exactly as shown above.
  • Add any missing runner entries under the runners block.

Step 3: Save & Verify

  1. Save the updated application.conf file after changes.
  2. Restart Ambience services to apply the new configuration.
  3. Re-run the report to confirm that rendering completes successfully.

What This Fix Achieves

  • Ensures jobs are picked up by the correct runner instead of sitting idle in the queue.
  • Prevents reports from timing out due to missing handlers.
  • Restores stable report rendering across all engines (DocX, ETL, RML).