Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Errors in data sources

Updated on November 23, 2022

Data source errors occur during the execution of a data source, and cause the data source to return incorrect, flawed, or missing data.

The following figure shows where in the data flow that data source errors can occur:

Data source execution showing where errors can occur in the data flow

Causes of data source errors include the following:

  • A source system or database is down, and the connection times out.
  • A request passed to the external system using the connector is invalid.
  • Credentials are invalid or are not authorized to get the data requested.
  • An internal system error occurred, either during loading or on the external system.

Information in data source error logs

When a data source error occurs in any data source other than an activity or data transform, the system adds the page property pyErrorPage to the data page. This property contains all error details so that users do not have to track them down across the various error properties and page messages used by connector, report definition, and lookup data sources. The details of a data source error contain the following information:

.pyStatusThe status when the data source finishes processing.

If an error occurs, its value is Fail.

.pyStatusMessageA message about the error that occurred during data source processing that forced the processing to stop. This is an informative message that you can use as a page message shown to users as an invocation error. This is also the value that is put into the default page message that the system adds when an error occurs.

The system always populates .pyStatus and .pyStatusMessage when an error occurs, and these rules can be used with any data source. When the source type is a connector of type SOAP, SAP, or dotNet, and a SOAP fault causes the error, the following properties are also populated:

.pyFaultCodeContains the code from the SOAP fault. See Section 5.4.6 SOAP Fault Codes of the W3C recommendations for more information.
.pyFaultReasonContains an explanation of the issue causing the SOAP fault that you can show to users or put in a message. See Section 5.4.2 SOAP Reason Element of the W3C recommendations for more information.
.pyFaultDetailContains the details of the SOAP fault, if provided, including application-specific error information. See Section 5.4.5 SOAP Detail Element of the W3C recommendations for more information.

Two additional properties are available for more advanced use cases, such as custom connector logic or load activities. These properties can provide additional detail in page messages:

.pxMessageSummary.pxErrorsWhen the data page has messages, this page list contains the message details, one page per message. The property.pyDescription contains the message.

If the message is attached to a property, the property .pyLabel contains the property reference.

.pyInvocationExceptionIf an error occurred because of an exception thrown during data source processing, this property contains the exception Java object.

The system only populates this property if the connector source type is SOAP, SAP, dotNet, or Java.

Handling data source errors

You perform error handling in the response data transform of a data source. The response data transform runs after the system obtains the data from the data source. It maps part or all of the information returned from the data source to the data page.

When making a new response data transform, the system adds several error-handling actions automatically, as in the following example:

Example of a new response transform with automatically generated error-handling actions
Example of a new response transform with automatically generated error-handling actions

The response data transform includes a reference to the pxDataPageHasErrors when rule. The nested section beneath the when rule is for entering the error handling logic. The when rule is the primary tool for conditionally running data source error-handling logic. You can conditionally change the when rule parameters to call a different source, and then retry persisting the when rule, or use another data page entirely for the logic to handle data source errors.

Example of a response data transform with the Run on data page option enabled
Example of a response data transform with the Run on data page option enabled

Pega Platform provides several tools for handling data source errors. A good place to start is the data transform pxErrorHandlingTemplate. This data transform includes the following sample actions that you can use for common data source error-handling tasks:

  • Read page messages on the data page.
  • Clear page messages from the data page so it does not stop work processing.
  • Return an invocation error by adding page messages, so that case processes pick the error up (remember to handle the error in your case layer).
  • Output messages to the system log.
  • Send an email to a system administrator or other stakeholder.

Using the default error-handling setup

To use the default error-handling setup, perform the following steps:

  1. Right-click the when rule step and click Enable.
  2. Add the error-handling logic in the steps nested below the when rule. You can also add the logic in a separate data transform that you can use across multiple data sources and call the transform from the data transform nested steps.

In these cases, selecting the Run response data transform on error check box on the data page is recommended. This runs the response data transform directly on the data page, saving memory and the processing cost of running a redundant page and mappings.

Note: The response data transform becomes optional when the class of the data source matches the class of the data page, because the data source can be run directly against the data page.

Error-handling data transform that you can reuse across various sources

To create your own error-handling data transform that you can reuse across various sources, you can either copy the logic from the template into your response data transform or save the template to your class and ruleset. All the data transform rows are disabled by default. You must right-click and enable the actions that you want to customize on each row.

When a dataSource page has errors, you can pull in data from a different data page instead, for example, to:

  • Reference another data page to pull data from an alternative data source
  • Reference another data page with the same data source for retrying
Note: Do not attempt to reference the currently loading data page from within the response data transform. This can cause errors when you try to load the data page.

Advanced data source error handling

To create a reusable error-handling data transform that works across all data sources, or uses the post-load activity to handle errors, refer to the data source that was used to conditionalize the actions or messages, and ensure that the actions or messages in the new error-handling data transform are conditionalized in the same way as the data sources.

In addition to the pyErrorPage property, all data pages contain an embedded page property called pySourcePage. This property contains up to five rules that provide detailed information about the data source that the system uses to load the data page. The following table lists the rules:

.pySourceTypeSpecifies one of the following source types: Connector, Report Definition, Lookup, Data Transform, or Activity.
.pyConnectorTypeIf the source type is a connector, this rule specifies the type of connector.

Specifies the identifier of the connector, report definition, data transform, or activity rule used as the data source.

This is empty for lookup data sources, because they do not use a rule.


Specifies the Applies To class of the connector, report definition, data transform, or activity rule used as the data source.

For lookup data sources, this is the identifier of the class used for the lookup.


Specifies the index of the data source on the data page form at the time of load.

The topmost source is 1, and the indexes increase going down the form.

Unlike pyErrorPage, pySourcePage is always present on loaded data page instances. You can always reference it from your data transforms or activities or view it in the clipboard to see which source was run.

Activity data sources

Using an activity as your data source reduces your error-handling options. However, several options are available in Pega Platform that make error handling in activities easier:

  • The system creates pyErrorPage and adds it to the step page whenever a Connect-* method is used to call a connector. pyErrorPage has the same information that is described in the Data Source Errors. Therefore, you can use the when rule pxDataPageHasErrors to verify whether there is an error on the Connect-* step page.

The system captures error information only for the connector types that the data page form supports as data sources. For other, more advanced connector types, you might need to look at the form to see what other error information is available and which properties contain the information. The following are some examples of error information for supported connector types:

  • Calls to report definitions that use Rule-Obj-Report-Definition.pxRetrieveReportData do not create a pyErrorPage. You need to continue to look for page messages to see if an error occurred and the root cause of the error. You can still use the when rule pxDataPageHasErrors to compare against the step page that the system used to call pxRetrieveReportData and determine whether an error occurred, or you can use the when rule hasMessages.
  • Lookups performed by using obj-open steps do not create a pyErrorPage. The system displays no error messages and you cannot use the when rule pxDataPageHasErrors to check for errors. Instead, use the when rule StepStatusFail. You also need to use the function @Utilities.getWorstMessage() to determine the root cause of the error and use the method Activity-Clear-Status to clear the fail status, if necessary (for example, if you intend to handle the error by performing a lookup on a different class instead).
  • Previous topic Use case: Referencing data in a data page by using parameters
  • Next topic Use case: Loading data into a page list property

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us