Edit

Share via

Troubleshooting report errors

  • Article

If reports fail to generate or take too long time to generate, you might need to investigate why. This article contains strategies for analyzing report telemetry to find possible root cases for such errors or slow performance.

Ways a report can fail

As described in the Report Object article, a report has code for its dataset, typically a layout used for rendering a document (Excel, Word, or PDF) and a request page. When the report runs, your AL code might call methods on the report object (static or on the report instance) and/or run code in triggers/event subscribers on report events.

A report in Business Central can fail in either of these phases:

  • In the request page
  • When generating the report dataset
  • When rendering the report with a layout
  • In any of the OnAfterDocument triggers

Report limits

The Business Central platform has built-in limits to protect the stability of the system from a single report consuming too many resources. Examples of limits are:

  • The maximum number of rows that can be processed in a report.
  • The maximum number of documents that can be merged in a report using a Word layout.
  • The maximum execution time that it can take to generate a report.

For more information on report limits, see Report limits

Troubleshooting report datasets and layouts

If a report layout isn't working as expected, you might need to investigate whether the issue is in the dataset.

Troubleshooting RDL report layouts

When you're developing and debugging an RDL report layout, it can be useful to get a copy of the report dataset in the XML format used by the RDL engine.

Tip

From the Business Central client, you can export report results as raw data to an XML file. Use the file to help validate that the report returns the expected data. To export a report dataset to XML, run the report and select the Send to > XML (data only) on the request page.

Troubleshooting Excel/Word report layouts

When you're developing and debugging an Excel/Word report layout, it can be useful to get a copy of the report dataset in Excel to see the actual data values in there.

Tip

From the Business Central client, you can export report results as raw data to a Microsoft Excel file. The file contains all columns of the dataset, but without the layout applied. Use the file to help validate that the report returns the expected data, and to ensure that the report layout controls match the dataset value types. To export a report dataset to Excel, run the report and select the Send to > Microsoft Excel Document (data only) on the request page. For more information, see Working with Reports - Send to Excel.

If the user sees this error message when running a report with a Word layout: You cannot run the report because the {0} layout contains section breaks that conflict with the sections in the report. Remove the section breaks from the report layout, and then run the report. then see this section to learn more: Using sections in a Word layout

Troubleshooting report AL code

When you're looking at the AL stacktrace from a report error message, it might not be obvious in which of these components the error was triggered. This is especially true for code failing in event subscribers on report events.

You can troubleshoot report errors using a debugger or with telemetry:

  • If the error occurs when running AL code, the most effective way to troubleshoot might be to attach a debugger.
  • If the error occurs in the Business Central platform or if you want to investigate an error that was reported by a user a few days ago, the most effective way to troubleshoot the report error is using telemetry. Report telemetry has information not available in the AL stacktrace, namely the Business Central server exception that triggered the error.

In the paragraphs that follow, you can read more about report error telemetry and how to use that to identify the cause and possible solutions or mitigations for report errors.

Reporting telemetry

Report telemetry gathers data about which reports are run on the environment. It provides information about whether the report succeeded, failed, or was canceled. For each report, it tells you how long it ran, how many SQL statements it executed, and how many rows it consumed.

You use this data to gather statistics on report usage, find failures in reports, or to help identify slow-running reports.

When you run a report, either from the UI, in a background session, or from a web service call, it might fail. The failure can either be in the AL code of the report or in the layout. When a report fails to generate, you get an RT0006 event in telemetry and the result column in the customDimensions includes the title of the exception that was thrown by the service or the AL code.

This KQL code can help you get started analyzing report failures:

traces
| where timestamp > ago(60d) // adjust as needed
| where operation_Name == "Failed report generation" // Note that in a later version of the schema, this field will not be used 
  or customDimensions.eventId == 'RT0006'            // introduced in version 16.1
| where customDimensions.result <> "Success"
| project timestamp
// in which environment/company did it happen
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
// in which extension/app
, extensionId = customDimensions.extensionId
, extensionName = customDimensions.extensionName
, extensionVersion = customDimensions.extensionVersion
, extensionPublisher = customDimensions.extensionPublisher
// in which object
, alObjectId = customDimensions.alObjectId
, alObjectName = customDimensions.alObjectName
, alObjectType = customDimensions.alObjectType
// what did the user do
, documentFormat = customDimensions.documentFormat   // documentFormat dimension was added in version 20.0
, LayoutAppId = customDimensions.layoutAppId         // layoutAppId was added in version 20.0
, LayoutName = customDimensions.layoutName           // layoutName dimension was added in version 20.0
, LayoutType = customDimensions.layoutType           // layoutType dimension was added in version 20.0
, reportAction = customDimensions.reportAction       // reportAction dimension was added in version 20.0
, reportingEngine = customDimensions.reportingEngine // reportingEngine dimension was added in version 17.3
// which user ran the report
, usertelemetryId = case(
  toint( substring(customDimensions.componentVersion,0,2)) >= 20, user_Id // usertelemetryId was added to the platform in version 20.0
, 'N/A'
)
// what happened
, alStackTrace = customDimensions.alStackTrace
, failureReason = customDimensions.result

For more information, see Report telemetry.

Reporting exceptions

In the following table, we list some common report exceptions thrown by the Business Central server and suggestions to how to fix them.

The different exceptions in the table are grouped by the following severities:

  • Error (this severity is likely an error in the report or the code around the report invocation)
  • TransientError (this severity was likely due to a transient issue in the infrastructure running Business Central and can likely be resolved by a retry)
  • Warning (this severity is likely not an error in the report. The issue can likely be resolved by fixing something in the environment, such as changing the permissions for a user/role)
Exception Severity Explanation
Canceled Warning Read more
ConnectionLostException TransientError Read more
DeadSqlConnectionException TransientError Read more
InconsistentReadException Warning Read more
IOException TransientError Read more
NavAdministratorMadeChangesException Error Read more
NavALException Error Read more
NavCompanyPermissionException Warning Read more
NavCreateScheduledTasksNotAllowedException Error Read more
NavCSideDataException Error Read more
NavCSideDuplicateKeyException Error Read more
NavCSideException Error Read more
NavCSideFilterException Error/Warning Read more
NavCSideRecordNotFoundException Error Read more
NavCSideSQLLockTimeoutException Warning Read more
NavCSideSqlTimeoutException TransientError Read more
NavCSideValidateTableRelationException Error Read more
NavEntitlementPermissionException Warning Read more
NavFilterException Error/Warning Read more
NavNCLArgumentException Error Read more
NavNCLCallbackNotAllowedException Error Read more
NavNCLConversionCastException Error Read more
NavNCLDateInvalidException Error Read more
NavNCLDebuggerActivityAbortedException Warning Read more
NavNCLDialogException Error Read more
NavNCLDocumentServiceException TransientError Read more
NavNCLEvaluateException Error Read more
NavNCLFieldNotFoundException Error Read more
NavNclHttpRequestException Error Read more
NavNCLInvalidPathException Error Read more
NavNCLMissingFileNameException Error Read more
NavNCLRecordNotOpenedException Error Read more
NavNCLReportDefinitionInvalidException Error Read more
NavNCLReportNoLayoutException Error Read more
NavNCLReportResultEmptyException Warning Read more
NavNCLStringLengthExceededException Error Read more
NavNCLXmlException Error Read more
NavOfficeDocumentRenderMaxRowsExceededException Error Read more
NavPermissionException Warning Read more
NavReportingServiceException TransientError Read more
NavSqlException Error Read more
NavTestFieldException Warning Read more
OpenXmlPackageException Error Read more
OutOfMemoryException Error Read more
SqlException TransientError Read more
XmlException Error Read more
XPathException Error Read more

Canceled

The report was cancelled either by the user or by the platform.

Suggested solution
This is not an error per se, but if you do not see any successful renderings of the report, you might have a bug in the AL code that generates the dataset.

ConnectionLostException

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

DeadSqlConnectionException

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

InconsistentReadException

Reports read data with UNCOMMITTED level. For this instance of the report, there was a conflict where data was modified by another session while reading the data in the session running the report

Suggested solution
Ask the user to re-run the report

IOException

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

The NavAdministratorMadeChangesException error typically occurs when an administrator has installed or updated an extension that have impact on the report (directly or via dependencies).

Suggested solution
Ask the user to re-run the report. Also, avoid installing extensions during working hours.

This typically happens if there is an error in the AL code generating the report dataset, not in the report layout

Suggested solution
You need a developer to debug the report code or the code running the report

The user running the report did not have access to the company.

Suggested solution
This is not an error in the report, but you might want to look into which users experience this and sort out the permission issue for them.

The report code is trying to start a background session, which is not allowed.

Suggested solution
This is usually due to the executing user not having sufficient rights to execute tasks.

It can be due to the report being executed by

  • A delegated admin,
  • An application which does not have API access,
  • A guest user without sufficient system entitlements.

Legacy error related to invalid data in the current context

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

The report code is trying to insert data into a table and there is already data there with the supplied key (either primary or unique)

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

There is an error in the report code (likely in the code generating the dataset) or in the code running the report.

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

The NavCSideFilterException error typically occurs when there’s an issue with a filter in a report, either when generating the dataset or when a user provides data in a request page. This could be due to a variety of reasons, such as an incorrect filter value, a problem with the filter syntax, or a data type mismatch.

Suggested solution
Here are some potential solutions:

Check the filter values (with the user): Make sure the filter values being used in the report are correct and valid.
Check the filter syntax: Ensure that the filter syntax is correct in the report dataset generation code. This includes the use of filter tokens, such as .. for ranges and | for alternatives.
Check for data type mismatches: Make sure that the data type of the filter value matches the data type of the field being filtered.

If the report is run in the background or from a web service call, then this is not a user error.

The NavCSideRecordNotFoundException error typically occurs when the server tries to access a record that doesn’t exist. This can happen in a report if the report is trying to access data from a table, but the specific record it’s looking for doesn’t exist in that table, or if the user is not allowed to access that record.

Suggested solution
Here are some potential solutions:
Check the data: Make sure the data the report is trying to access actually exists in the database.
Check the report code: There might be an issue with how the report is trying to access the data. You might need to modify the report code to correctly handle cases where a record doesn’t exist.

The report code tried to get a lock on data, but another process had a lock on the same data. After 30 seconds, the report proces had to timeout and give up getting a lock on the data.

Suggested solution
The user should retry running the report. If the issue persists, then the administrator might need to look into telemetry for lock timeouts to find which process is locking data.

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

A field table relation cannot be validated

Suggested solution
Missing data in the related table or incorrect data in the current field that does not match the required fiels in the related table.

The user running the report has a license that does not allow running the report.

Suggested solution
This is not an error in the report, but you might want to look into which users experience this and sort out the license issue for them.

The NavFilterException error typically occurs when there’s an issue with a filter in a report, either when generating the dataset or when a user provides data in a request page. This could be due to a variety of reasons, such as an incorrect filter value, a problem with the filter syntax, or a data type mismatch.

Suggested solution
Here are some potential solutions:

  • Check the filter values (with the user): Make sure the filter values being used in the report are correct and valid.
  • Check the filter syntax: Ensure that the filter syntax is correct in the report dataset generation code. This includes the use of filter tokens, such as .. for ranges and | for alternatives.
  • Check for data type mismatches: Make sure that the data type of the filter value matches the data type of the field being filtered.


If the report is run in the background or from a web service call, then this is not a user error.

Invalid parameter has been passed on to an AL runtime method.

Suggested solution
You need a developer to debug the report. If the report was supplied by Microsoft or an ISV, then create a support request.

The report is running in the background or triggered from a webservice and the code is trying to open UI from any function in AL that requires the client , for example confirmation, a file upload, opening a page etc.

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

There is an error in the report AL code (not the layout) related to invalid type conversion.

Suggested solution
You need a developer to debug the report. If the report was supplied by Microsoft or an ISV, then create a support request.

A string cannot be converted to a date type.

Suggested solution
Incorrect string format that cannot be converted to a date in the current regional setup. Inspect the data behing the report or change the regional settings to fit report requirements. In BC 23 and later, try to set the format region in the request page and rerun the report.

This happens when a developer is debugging a report

Suggested solution
Not an error

The NavNCLDialogException error happens when a error funtion has been called in the report.

Suggested solution
The error messages will in most cases provide the necessary information to mitigate the problem. If not, you need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

Unabler to evaluate the input string to the desired database.

Suggested solution
You need a developer to debug the report. If the report was supplied by Microsoft or an ISV, then create a support request.

The NavNCLFieldNotFoundException typically occurs when a field that the report is trying to access is not found. This is typically due to outdated field refs in AL code that try to address a table field using an index that is no longer valid.

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

The NavNclHttpRequestException error in AL code for Microsoft Dynamics 365 Business Central typically occurs when there’s an issue with the HTTP request made to a web service. This could be due to a variety of reasons such as network issues, incorrect endpoint URL, or issues with the request parameters.

Suggested solution
An error in (third-party) extension code being called from report triggers. You need a developer to debug the report code. If the report was supplied by Microsoft or an ISV, then create a support request.

This typically happens in processing-only reports. Some typical scenarios are code that tries to read or write a file using an invalid path (OnPrem) or a path outside of the users allowed temp area (SaaS).

Suggested solution
You need a developer to debug the report. If the report was supplied by Microsoft or an ISV, then create a support request.

This typically happens in processing-only reports

Suggested solution
First check the parameters on the request page. Could be a missing file name in field that does not have a proper field validation. You might need a developer to debug the report code or the code running the report

AL runtime error caused by programming errror when the code does not open a record reference before use.

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

Invalid RDLC layout which need a review by a developer.

Suggested solution
You need a developer to debug the report. If the report was supplied by Microsoft or an ISV, then create a support request.

There is an error in the report code or layout setup in the application if the selected has been set to a user defined layout or the layout selection points to an uninstalled layout from a report extension.

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

When the report dataset does not have any data, we show a dialog to the user.

Suggested solution
This is not an error per se, but if you do not see any successful renderings of the report, you might have a bug in the AL code that generates the dataset. The typical root cause for this error is incorrect filters on the request page that result in an empty data set.

This can happen when you assign an unlimited string to a string with a fixed length. The error will occur if the source string is longer than the allocated length in the target.

Suggested solution
You need a developer to debug the report or the code running the report. If the report was supplied by Microsoft or an ISV, then create a support request.

This typically happens if there is an error in the XML of the request page

Suggested solution
You need a developer to debug the report code or the code running the report

The Business Central service cannot process the report because the dataset contains too many rows.

Suggested solution
Update the filter on the report to limit the number of rows. The maximum number of rows can be controlled in the Report Limits page or in the advanced tab on the request page. Notice that setting the limit too high, can put the node at risk due to high memory usage (can result in Out-of-memory exception) and constrain other users on the system.

The user running the report was missing permissions to run the report or to some of the data needed in the report dataset.

Suggested solution
This is not an error in the report, but you might want to look into which users experience this and sort out the permission issue for them.

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

This happens when the TESTFIELD function test a value in a field and it does not match the expected value.

Suggested solution
This is not an error per se, but if you do not see any successful renderings of the report, you might have a bug in the AL code for the request page.

OpenXmlPackageException

This typically happens if there is an error in a Word layout

Suggested solution
You need a developer to debug the Word report layout. If the layout was supplied by Microsoft or an ISV, then create a support request.

OutOfMemoryException

The Business Central service cannot process the report because the memory needed to do that exceeds the limit on the platform

Suggested solution
Set a filter in the report to limit the number of rows in the data set.

SqlException

This is a transient error in the Business Central service.

Suggested solution
Ask the user to re-run the report

XmlException

This typically happens if there is an error in a Word layout

Suggested solution
You need a developer to debug the Word report layout. If the layout was supplied by Microsoft or an ISV, then create a support request.

XPathException

This typically happens if there is an error in the XML of the request page or if the xml data set for Word based reports is corrupted.

Suggested solution
You need a developer to debug the report code or the code running the report

Report performance

Reports generally fall into two categories. They can be specific to a single instance of an entity, like an invoice. Or, they can be of a more analytical nature that joins data from multiple instances of multiple entities. Typically, performance issues in reports lie in the latter category. The following articles contain advice about implementing faster reports:

  • Use Read Scale-Out to read data from a read-only copy of the database, see Using Read Scale-Out for Better Performance for more information.
  • Use Partial Records to reduce the data loaded from the database, see Using Partial Records for more information.
  • Use AL queries to optimize the way data is read from the database, see Queries in Business Central for more information.
  • Compared to Word layouts, RDL layouts can result in slower performance with document reports, especially for actions related to the user interface (like sending emails). For more information, see Creating an RDL Layout Report.
  • Can you run the report in the background? It will not make it run faster, but the user might feel this way (as they are not blocked in the UI while waiting on the report to finish). For more information, see Schedule a report.

Tip

From the Business Central client, you can export report results as raw data to a Microsoft Excel file. The file contains all columns of the dataset, but without the layout applied. Use the file to help validate that the report returns the expected data, and to ensure that the report layout controls match the dataset value types. To export a report dataset to Excel, run the report and select the Send to > Microsoft Excel Document (data only) on the request page. For more information, see Working with Reports - Send to Excel.

For more information, see Report performance.

Testing a report
Report performance
Report telemetry